How to Create or Update Organisation from XML

Warning: Beta software This API is in beta stage and may be subject to change. Therefore, we do not recommend using this in production.

Interested in this feature? Please reach out to mobility-services-developer@cisco.com

CreateOrUpdateOrganisationFromXml is a method that allows you to create or update organisation information from an XML file in the IR21 database. The XML file should contain the organisation data in the GSMA RAEX IR.21 XML format (see GSMA PRD IR.21 v17.0). Use this function when you have access to IR.21 records in this format.

This method is part of the IR21 API and belongs to the Ir21Service.

XML File Format

The XML file should contain organisation data in the following format:

<?xml version="1.0" encoding="UTF-8"?>
<organisation>
  <name>Example Telecom</name>
  <country>Norway</country>
  <countryInitials>NOR</countryInitials>
  <tadig>EXMPL</tadig>
  <mccmnc>
    <mcc>242</mcc>
    <mnc>01</mnc>
  </mccmnc>
  <realm>epc.mnc001.mcc242.3gppnetwork.org</realm>
  <gtPrefix>4790000000</gtPrefix>
</organisation>

Prerequisites

  1. An OAuth 2.0 client
  2. A client access token

Code Dependencies

<dependency>
  <groupId>com.wgtwo.api.v1.grpc</groupId>
  <artifactId>ir21</artifactId>
  <version>1.16.3</version>
</dependency>

Code

The examples below demonstrate how to use the CreateOrUpdateOrganisationFromXml function.

The grpcurl example uses base64 -i example-organisation.xml to encode the XML file content, as the API expects the XML data as base64-encoded bytes.

You can test our APIs without authorization by targeting sandbox.api.shamrock.wgtwo.com instead of api.{region}.wgtwo.com and removing any authorization from the request/code sample.


#!/usr/bin/env bash
XML_CONTENT=$(base64 -i example-organisation.xml)
grpcurl \
  -d '{
    "datasetUuid": "rM/IlHhOSQiHoQFiUHv6ww==",
    "xmlFile": "'"$XML_CONTENT"'",
    "comment": "Organisation imported from XML file"
  }' \
  sandbox.api.shamrock.wgtwo.com:443 \
  wgtwo.ir21.v1.Ir21Service/CreateOrUpdateOrganisationFromXml


package com.example.ir21

import com.google.protobuf.ByteString
import com.wgtwo.api.v1.ir21.Ir21ServiceGrpcKt
import com.wgtwo.api.v1.ir21.createOrUpdateOrganisationFromXmlRequest
import io.grpc.ManagedChannelBuilder
import io.grpc.Status
import io.grpc.StatusException
import kotlinx.coroutines.runBlocking
import kotlin.test.assertFailsWith

private val channel = ManagedChannelBuilder.forAddress("sandbox.api.shamrock.wgtwo.com", 443).build()
private val stub = Ir21ServiceGrpcKt.Ir21ServiceCoroutineStub(channel)

fun main() = runBlocking {
    // First create a dataset
    val createDatasetRequest = com.wgtwo.api.v1.ir21.createDatasetRequest {
        comment = "Dataset for XML organisation example"
    }
    val createDatasetResponse = stub.createDataset(createDatasetRequest)
    val createdDatasetUuid = createDatasetResponse.uuid

    // Example in GSMA RAEX IR.21 XML format (see GSMA PRD IR.21 v17.0).
    val xmlContent = """
        <?xml version="1.0" encoding="UTF-8"?>
        <TADIGRAEXIR21 xmlns="https://infocentre.gsm.org/TADIG-RAEX-IR21">
          <OrganisationInfo>
            <OrganisationName>Example Telecom</OrganisationName>
            <CountryInitials>NOR</CountryInitials>
            <NetworkList>
              <Network>
                <TADIGCode>EXMPL</TADIGCode>
                <NetworkData>
                  <LTEInfoSection>
                    <LTEInfo>
                      <RoamingInterconnection>
                        <Diameter>
                          <EPCRealmsForRoamingList>
                            <EPCRealmsForRoaming>epc.mnc001.mcc242.3gppnetwork.org</EPCRealmsForRoaming>
                          </EPCRealmsForRoamingList>
                        </Diameter>
                      </RoamingInterconnection>
                    </LTEInfo>
                  </LTEInfoSection>
                  <RoutingInfoSection>
                    <RoutingInfo>
                      <CCITT_E212_NumberSeries>
                        <MCC>242</MCC>
                        <MNC>01</MNC>
                      </CCITT_E212_NumberSeries>
                      <CCITT_E164_NumberSeries>
                        <GT_NumberRanges>
                          <RangeData>
                            <NumberRange>
                              <CC>47</CC>
                              <NDC>90000000</NDC>
                            </NumberRange>
                          </RangeData>
                        </GT_NumberRanges>
                      </CCITT_E164_NumberSeries>
                    </RoutingInfo>
                  </RoutingInfoSection>
                </NetworkData>
              </Network>
            </NetworkList>
          </OrganisationInfo>
        </TADIGRAEXIR21>
    """.trimIndent()

    val createOrUpdateOrganisationFromXmlRequest = createOrUpdateOrganisationFromXmlRequest {
        datasetUuid = createdDatasetUuid
        xmlFile = ByteString.copyFromUtf8(xmlContent)
        comment = "Organisation imported from XML file"
    }
    println("createOrUpdateOrganisationFromXmlRequest:
$createOrUpdateOrganisationFromXmlRequest")

    val createOrUpdateOrganisationFromXmlResponse = stub.createOrUpdateOrganisationFromXml(createOrUpdateOrganisationFromXmlRequest)
    println("createOrUpdateOrganisationFromXmlResponse:
$createOrUpdateOrganisationFromXmlResponse")

    // Test error case - empty XML file
    val createOrUpdateOrganisationFromXmlRequestWithEmptyXml = createOrUpdateOrganisationFromXmlRequest {
        datasetUuid = createdDatasetUuid
        xmlFile = ByteString.EMPTY
        comment = "This should fail"
    }

    val exception = assertFailsWith<StatusException>("exception is not a StatusException") {
        stub.createOrUpdateOrganisationFromXml(createOrUpdateOrganisationFromXmlRequestWithEmptyXml)
    }

    assert(exception.status.code == Status.INVALID_ARGUMENT.code) {
        "status code is not INVALID_ARGUMENT: ${exception.status.code}"
    }
}

Example Results Success

{
  "uuid": "eG1sLW9yZy11dWlkLTEyMzQtNTY3OC05YWJjLWRlZjAxMjM0NTY3OA=="
}

uuid: "eG1sLW9yZy11dWlkLTEyMzQtNTY3OC05YWJjLWRlZjAxMjM0NTY3OA=="

Example Results Error

ERROR:
  Code: InvalidArgument
  Message: xml_file is required

Status code: INVALID_ARGUMENT
Status description: xml_file is required

Read More