Workorders API

This chapter describes the Workorders API.

Using the Workorders API

These APIs talk with any cloud-based management services. It contains seven primary action calls sent using the SOAP envelope over HTTP(s):

https://<server_address> :portnumber/nbapi/workorder

Audit API Method Calls

RequestUserAuthentication

This call requests user authentication with the cloud service. The utility field technician must sign in to IoT FND before they can use the field tool. The username and password is encrypted and cached in the device for remote connections. Below is the definition for this action based on the Cisco HSL language:

Struct UserAuthInfo

String  appVersion		## CG-NMS application version for version control
String  scriptVersion			## CG-NMS button script version for version control

Enum UserAuthResult

“AUTH_OK”							## Authentication OK
“AUTH_OK_NO_PERMISSION”							## Authentication OK but no permission to access resources
“AUTH_OK_VER_MISMATCH”							## Authentication Fail - User/Pwd may be ok but the version is
							## not expected
"AUTH_FAIL"							## NOTE:  This may never appear in the SOAP response as some
							## web servers will return http status code 40x if auth fails.
							## Both the 40x status code and AUTH_FAIL in the SOAP response
							## are handled.

Struct UserAuthResponseInfo

UserAuthResult		userAuthResult			## Authentication result
String		expectAppVer			## [Optional] If the current app version
				## needs to be upgraded
String			expectScriptVer			## If the current script version needs to be
			## upgraded

Struct UserAuthResponse

Input: 

UserAuthInfo          userAuthInfo

Output:

UserAuthResponse  RequestUserAuthenticationResponse

Action RequestUserAuthentication

UserAuthResponseInfo	userAuthResponse		## Authentication result

SOAP XML Request Format

POST  /nms/fieldtool   HTTP/1.1 
Host: sample.cisco.com:8080 
Content-Length: nnn 
Authorization: Basic bW2eFaHU5K+ 
SOAPAction: http://workorder.nbapi.cgms.cisco.com/RequestUserAuthentication
Connection: close 
Content-type: text/xml; charset=”UTF-8” 
User-Agent: Cisco Device Management Application 
<?xml version=”1.0” encoding=”utf-8”?> 
<SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:m="http://workorder.nbapi.cgms.cisco.com/"> 
    <SOAP-ENV:Body> 
        <m:RequestUserAuthentication> 
            <userAuthInfo> 
                <appVersion>1.2.23.128</appVersion> 
                <scriptVersion>2.3.4</scriptVersion> 
            </userAuthInfo> 
        </m:RequestUserAuthentication> 
    </SOAP-ENV:Body> 
</SOAP-ENV:Envelope>

Response

HTTP/1.1   200 OK 
Content-type: text/xml; charset=”UTF-8” 
Content-Length: nnn 
<?xml version=”1.0” encoding=”utf-8”?> 
<SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”>   
    <SOAP-ENV:Body> 
        <m:RequestUserAuthenticationResponse xmlns:m="http://workorder.nbapi.cgms.cisco.com/"> 
            <userAuthResponse> 
                 <userAuthResult>AUTH_OK</userAuthResult> 
                 <expectAppVer>1.2.25.02</expectAppVer> 
                 <expectScriptVer>2.3.5</expectScriptVer> 
            </userAuthResponse>  
        </m:RequestUserAuthenticationResponse> 
    </SOAP-ENV:Body> 
</SOAP-ENV:Envelope>

RequestSignedAuthorization

This call retrieves work authorizations from the cloud service. For security, the utility technician requests work authorizations from the management cloud service before they can complete the work order.

Enum UserRole

“ADMIN”			## Unlimited commands
“TECH”			## Most commands and interface configure
“VIEWER”			## Read only commands

Struct DeviceInfo

String			deviceId					## Device unique ID such as serial number 
String			ssid 					## WiFi SSID for a specific FAR device
String			passphrase					## WiFi Passphrase for a specific FAR device
String			firmwareVersion					## [Optional] Firmware version for this device. If present,
								## CG-NMS needs to request it from NMS/Cloud
String			configurationId					## [Optional] Unique configuration profile id for this
								## device. If present, Bahamas needs to request it from
								## NMS/Cloud

Attribute CanonicalizationTheMethod

String			Algorithm

Attribute SignatureTheMethod

String			Algorithm

Attribute TransformTheMethod

String			Algorithm

Attribute DigestTheMethod

String			Algorithm

Struct TransformsInfo

TransformTheMethod						TransformMethod

Struct SignatureReference

TransformsInfo						Transforms
DigestTheMethod						DigestMethod
String						DigestValue

Struct SignatureSignedInfo

CanonicalizationTheMethod							CanonicalizationMethod
SignatureTheMethod							SignatureMethod
SignatureReference							Reference							## Signed info reference

Struct SignatureX509Data

String			X509SubjectName
String			X509Certificate

Struct SignatureKeyInfo

SignatureX509Data					X509Data

Struct XMLSignature

SignatureSignedInfo						SignedInfo
String						SignatureValue
SignatureKeyInfo						KeyInfo

Struct SignedAuth

String				version				## Version of the schema for signed authorization
String				authId				## UID in the string format
String				authCreated				## Date String in UTC format
String				deviceId				## Device unique ID such as serial number
String				technician				## Name of the technician requesting the authorization
UserRole				userRole				## What role to manage the FAR
String				startDateTime				## Date in UTC string to indicate valid-from
String				endDateTime				## Date in UTC string to indicate valid-to
XmlSignature				Signature				## The signature info to be passed to FAR

Struct SignedAuthorization

SignedAuth				signedAuth
DeviceInfo				deviceInfo				##[Optional]

Struct SignedAuthorizationResponse

SignedAuthorization[]						signedAuthorization

Action RequestSignedAuthorization

Input: 

String				technicianUserName						## The technician username registered with NMS
String				workOrderNumber						## If the technician knows a specific name, he can
										## put it here; otherwise put null string will
										## retrieve all the orders assigned to him

Output:

SignedAuthorizationResponse								RequestSignedAuthorizationResponse

SOAP XML Request Format Request

POST  /nbapi/workorder   HTTP/1.1 
Host: 128.154.157.111:8443  
Content-Length: nnn 
SOAPAction: http://workorder.nbapi.cgms.cisco.com/RequestSignedAuthorization
Authorization: Basic eWfqD54DefCdEf4B3aA= 
Connection: close 
Content-type: text/xml; charset=”UTF-8” 
User-Agent: Cisco Device Management Application 
<?xml version=”1.0” encoding=”utf-8”?> 
<SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:m="http://workorder.nbapi.cgms.cisco.com/">                                                         
    <SOAP-ENV:Body> 
        <m:RequestSignedAuthorization> 
            <technicianUserName>bob</technicianUserName> 
            <workOrderNumber>abcd-efgh-hijk</workOrderNumber> 
        </m:RequestSignedAuthorization> 
    </SOAP-ENV:Body> 
</SOAP-ENV:Envelope>

Response

HTTP/1.1   200 OK 
Content-type: text/xml; charset=”UTF-8” 
Content-Length: nnn 
<?xml version=”1.0” encoding=”utf-8”?> 
<SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”> 
    <SOAP-ENV:Body> 
        <m:RequestSignedAuthorizationResponse xmlns:m="http://workorder.nbapi.cgms.cisco.com/"> 
             <signedAuthorization> 
                 <signedAuth> 
                    <version>1</version> 
                    <orderNumber>9429C098-495A-402C-9456-57F3CC7475BF</orderNumber> 
                    <authCreated>2011-09-20T03:48:28Z</authCreated> 
                    <userRole>tech</userRole> 
                    <technicianUserName>bob</technicianUserName> 
                    <deviceId>AB193AQ</deviceId> 
                   <startDate>2011-09-20T03:48:28Z</startDate> 
                    <endDate>2011-09-20T09:48:28Z</endDate> 
                    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> 
                          <SignedInfo> 
                                <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"/> 
                                <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> 
                                <Reference URI=""> 
                                      <Transforms> 
                                           <TransformMethod Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/> 
                                      </Transforms> 
                                      <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/> 
                                      <DigestValue>CpJhSOAalu8QJeUX2wiaGG0ZGEk=</DigestValue> 
                                </Reference> 
                            </SignedInfo> 
                            <SignatureValue> 
                                lgkxDOwRdaAUOvKTVyzbdsLL0c4ONB51LTmmOdWXCYMErwMSy53nWUencU 
                                h14cmR4rPsumdYWJzCqJik2oci6p8uMnLDCv8= 
                            </SignatureValue> 
                            <KeyInfo> 
                                <X509Data> 
                                    <X509SubjectName> 
                                        CN=My Name,O=Test Certificates Inc.,C=US 
                                    </X509SubjectName> 
                                    <X509Certificate> 
                                        MIIB9zCCAWCgAwIBAgIERZwdkzANBgkqhkiG9w0BAQUFADBAMQswCQYD 
                                        VQQGEwJVUzEfMB0GA1UEChMWVGVzdCBDZXJ0aWZpY2F0ZXMgSW5jLjE 
                                        MA4GA1UEAxMHTXkgTmFtZTAeFw0wNzAxMDMyMTE4MTFaFw0zMTA4M 
                                        ... 
                                    </X509Certificate> 
                                </X509Data> 
                            </KeyInfo> 
                        </Signature> 
                 </signedAuth> 
                 <deviceInfo> 
                     <deviceId>AB193AQ</deviceId> 
                     <ssid>testfar</ssid> 
                     <passphrase>cisco123</passphrase> 
                     <firmwareVersion>1.2.3</firmwareVersion> 
                     <configurationId>123.234</configurationId> 
                 </deviceInfo> 
             </signedAuthorization> 
             <signedAuthorization> 
                 ...  ...  ...  ...  ... 
             <signedAuthorization> 
        </m:RequestSignedAuthorizationResponse>  
    </SOAP-ENV:Body> 
</SOAP-ENV:Envelope>

UploadServiceReport

This call uploads the service report to the cloud service. IoT FND tracks the service status for a work order, and prompts the utility technician to mark status field as job complete, job expired, job incomplete, and so on. Once work order status is reported, the work order can be safely removed from IoT FND. Work orders are archived on the NMS server.

Enum ServiceReportResult

“REPORT_OK”
“REPORT_FAIL”

Enum ServiceStatus

“Completed”					# The work is done
“Incomplete”					# The work can not be completed due to some reasons
“Expired”					# The work authorization is expired

Struct ServiceStatusReport

String				orderNumber
String				deviceId
String				technicianUserName
ServiceStaus 				status

Struct ServiceStatusResponse

ServiceReportResult						result
String						comment				## [Optional]

Struct ServiceReportResponse

ServiceStatusResponse						serviceReportResponse

Action UploadServiceReport

Input: 

ServiceStatusReport []							serviceStatusReport

Output:

ServiceReportResponse							UploadServiceReportResponse

SOAP XML Request Format

POST  /nms/fieldtool   HTTP/1.1 
Host: sample.cisco.com:8080 
Content-Length: nnn 
Authorization: Basic bW2eFaHdD3K 
SOAPAction: [http://workorder.nbapi.cgms.cisco.com/UploadServiceReport 
] Connection: close 
Content-type: text/xml; charset=”UTF-8” 
User-Agent: Cisco Device Management Application 
<?xml version=”1.0” encoding=”utf-8”?> 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:m="http://workorder.nbapi.cgms.cisco.com/"> 
    <SOAP-ENV:Body> 
        <m:UploadServiceReport> 
            <serviceStatusReport> 
                <orderNumber>9429C098-495A-402C-9456-57F3CC7475BF </orderNumber> 
                <deviceId>AB193BQ</deviceId> 
                <technicianUserName>Bob</technicianUserName> 
                <status>Completed</status> 
            </serviceStatusReport> 
            <serviceStatusReport> 
                <orderNumber>8688C098-495A-402C-2356-57F3CC7475BF </orderNumber> 
                <deviceId>CC210EQ</deviceId> 
                <technicianUserName>Alex</technicianUserName> 
                <status>Expired</status> 
            </serviceStatusReport> 
        </m:UploadServiceReport> 
    </SOAP-ENV:Body> 
</SOAP-ENV:Envelope>

Response

HTTP/1.1   200 OK 
Content-type: text/xml; charset=”UTF-8” 
Content-Length: nnn 
<?xml version=”1.0” encoding=”utf-8”?> 
<SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”> 
    <SOAP-ENV:Body> 
        <m:UploadServiceReportResponse xmlns:m="http://workorder.nbapi.cgms.cisco.com/"> 
              <serviceReportResponse> 
                   <result>REPORT_FAIL</result> 
                   <comment>Syntax Error</comment> 
              </serviceReportResponse>  
        </m:UploadServiceReportResponse>    
    </SOAP-ENV:Body> 
</SOAP-ENV:Envelope>