Integrating with GPS API Oracle Field Service Cloud · Integrating with GPS API Chapter 1...

Oracle Field Service CloudIntegrating with GPS API

19A


19A

Part Number: F13261-01

Copyright © 2019, Oracle and/or its affiliates. All rights reserved

Authors: The Field Service Cloud Information Development Team

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected byintellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast,modify, license, transmit, distribute, exhibit, perform, publish, or display in any part, in any form, or by any means. Reverse engineering, disassembly, ordecompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them tous in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the followingnotice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulationand agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operatingsystem, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictionsapplicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use inany inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerousapplications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. OracleCorporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks orregistered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks ofAdvanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. OracleCorporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, andservices unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for anyloss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreementbetween you and Oracle.

The business names used in this documentation are fictitious, and are not intended to identify any real companies currently or previously in existence.


Contents

Preface .................................................................................................................. i

1 Introduction 1Document Purpose .................................................................................................................................................... 1

Scope of the Document ............................................................................................................................................. 1

Target Audience ......................................................................................................................................................... 1

Accessing the APIs .................................................................................................................................................... 1

Glossary ..................................................................................................................................................................... 1

2 GPS API Overview 3GPS API Overview ..................................................................................................................................................... 3

3 Accessing the GPS API 5User Authentication Structure ..................................................................................................................................... 5

4 GPS API Methods 7GPS API Methods ...................................................................................................................................................... 7

5 GPS API Methods Description 9'set_position' Method ................................................................................................................................................. 9

'get_position' Method ............................................................................................................................................... 11

6 Fault Responses 15Fault Responses ....................................................................................................................................................... 15

Error Messages ........................................................................................................................................................ 15


Preface

Preface

This preface introduces information sources that can help you use the application and this guide.

Using Oracle Applications

To find guides for Oracle Applications, go to the Oracle Help Center.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website.

Videos included in this guide are provided as a media alternative for text-based topics also available in this guide.

Contacting Oracle

Access to Oracle SupportOracle customers that have purchased support have access to electronic support through My Oracle Support. Forinformation, visit My Oracle Support or visit Accessible Oracle Support if you are hearing impaired.

Comments and SuggestionsPlease give us feedback about Oracle Applications Help and guides. Please take one of the following surveys:

• For web-based user guide, Web-based User Guide Survey

• For tutorial feedback, Tutorial Survey

i

http://docs.oracle.com/

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs

http://ora-gcp1.custhelp.com/ci/documents/detail/5/2295/12/369d658f1a7917d7400a4e1af2bef7eaac486b07

http://ora-gcp1.custhelp.com/ci/documents/detail/5/2296/12/43f59803d4b334caea4e74d1546a10a0d99ff420


Preface

ii


Chapter 1Introduction

1 Introduction

Document Purpose

This document is a developer's guide for the GPS API. The GPS API is available as part of the Oracle Field Service Cloudplatform.

It contains information to enable the integration of an external GPS system with Oracle Field Service Cloud.

Scope of the Document

The document describes the elements of SOAP technology and its usage when creating client applications for interacting withthe GPS module of OFSC system.

Target Audience

This document is intended for software developers, implementing SOAP clients for interaction with the OFSC GPS module.

Accessing the APIs

To access the Oracle Field Service Cloud APIs, you must use the https://api.etadirect.com URL scheme. All old URLschemes such as, companyname.etadirect.com, na.etadirect.com, eu.etadirect.com, and so on are deprecated for OracleField Service Cloud versions 15.8 and later.

For example, if you are using https://companyname.etadirect.com/soap/inbound/?wsdl to access the Inbound WSDL API,the URL per the new scheme is https://api.etadirect.com/soap/inbound/?wsdl.

Glossary

Term Explanation

Activate route

Start the work day

1


Chapter 1Introduction

Term Explanation

Activity

Entity of the Oracle Field Service Cloud system that represents any time-consuming activity of theresource

Client Application

See SOAP Client Application

Decimal degrees

Representation of latitude and longitude geographic coordinates as decimal fractions

Delivery

In this context, transportation of GPS data from external GPS service to Oracle Field Service Cloud

GPS

Global Positioning System – space-based global navigation satellite system, providing data onlocation of objects on the Earth in a given moment of time

ISO 8601 format See http://en.wikipedia.org/wiki/ISO_8601

Bucket

Entity appearing on the resource tree which can contain resources of a defined type and beassigned activities

Capacity

Workforce possessing the necessary work skills available at a certain moment of time

Capacity category

Predefined set of work skills, work skill groups and time slots within which they are considered bythe Capacity Management API

Customer

End-customer, entity that benefits from the activity

ISO 8601 format

see http://en.wikipedia.org/wiki/ISO_8601

SOAP

Lightweight protocol for exchange of information in a decentralized, distributed environment

SOAP 1.1 See http://www.w3.org/TR/2000/NOTE-SOAP-20000508/

SOAP Interface

Interface used to receive requests and return responses via SOAP

SOAP Client Application

Application running at the Client's site and providing interaction with Oracle Field Service Cloudserver via SOAP

SOAP Fault

SOAP element used to carry error and/or status information in a SOAP message

SOAP Faultcode

SOAP element intended to be used by software to provide an algorithmic mechanism for identifyingthe fault

SOAP Faultstring

SOAP element intended to provide a human readable explanation of the fault and not intended foralgorithmic processing

User

1) Person using Oracle Field Service Cloud 2) Entity used for authentication and authorization, allowing people or external software to accessOracle Field Service Cloud

2

http://en.wikipedia.org/wiki/ISO_8601


Chapter 2GPS API Overview

2 GPS API Overview

GPS API Overview The aim of the GPS module is to support integration of the OFSC system with external GPS-based systems, providingposition tracking of GPS-enabled devices (hereinafter – the objects).

This module works as a data cache and security firewall, and allows providing GPS data to OFSC quickly and safely.

The GPS interface provides OFSC with data that enables it to see the current and earlier positions of an object on the map,and shows their trace (it is shown as a sequence of blue dots).

3


Chapter 2GPS API Overview

4


Chapter 3Accessing the GPS API

3 Accessing the GPS API

User Authentication Structure All API methods use the 'user' structure as authentication to determine the permissions of the Oracle Field Service Cloudclient company user.

The following table describes the Oracle Field Service Cloud SOAP authentication structure mandatory fields.

Name Type Description

now

string

current time in ISO 8601 format

company

string

case-insensitive identifier of the Client for which data is to be retrieved provided by Oracle during integration

login

string

case-insensitive identifier of a specific user within the Company provided by Oracle during integration

auth_string

string

authentication hash; Use one of the following:

• auth_string = SHA256(now + SHA256(password+SHA256(login)));

where, 'password' is a case-sensitive set of characters used for user authenticationprovided by Oracle during integration.

• auth_string = md5(now + md5(password));

where, 'password' is a case-sensitive set of characters used for user authenticationprovided by Oracle during integration.

For example:

For the password "secret123", login “soap”, and date “2014-01-10T13:56:50Z“, the auth_string is calculated as follows:

auth_string = SHA256( "2014-01-10T13:56:50Z" + SHA256( "secret123" + SHA256(“soap”))) =b477d40346ab40f1a1a038843d88e661fa293bec5cc63359895ab4923051002a

<user>

<now>2014-01-10T13:56:50Z</now>

<login>soap</login>

<company>in132</company>

<auth_string>b477d40346ab40f1a1a038843d88e661fa293bec5cc63359895ab4923051002a</auth_string>

5


Chapter 3Accessing the GPS API

</user>

Authentication The 'user' structure is used for the request authentication. The relevant error is returned if the authentication fails.

If you created a login policy to allow access for only certain IP addresses, the login policy is applicable to the APIs as well.

For example, you defined to allow requests only from IP address 110.0.133.185 for a User Type="API_User" and with loginpolicy "API_login_policy". This implies that authentication fails for a user accessing the APIs from an IP address other than110.0.133.18, though the login credentials are correct.

Number Login Description

1

now

is different from the current time on the server and this differenceexceeds the predefined time-window (30 minutes by default)

2

company

cannot be found in the Oracle Field Service Cloud

3

login

cannot be found for this company

4

user with this 'login' is not authorized to usethe current method

5

auth_string

is not equal to md5(now+md5(password)) or auth_string =SHA256(now + SHA256(password+SHA256(login)));;

For example: 'now' = "2005-07-07T09:25:02+00:00"and password = "Pa$$w0rD" then md5 (password) ="06395148c998f3388e87f222bfd5c84b" concatenated string = ="2005-0707T09:25:02+00:0006395148c998f3388e87f222bfd5c84b"auth_string should be: auth_string ="62469089f554d7a38bacd9be3f29a989"

Otherwise authentication is successful and the request is processed further.

6


Chapter 4GPS API Methods

4 GPS API Methods

GPS API Methods There following operations are used to deliver GPS data by means of SOAP:

The following table describes the GPS API methods.

Method Can be used to... Description

set_position

...update the object position

Enables the external system to update information aboutlast known position(s) of the objects(s) specified by theidentifier(s)

get_position

… obtain information on the objectposition

Enables OFSC to obtain information about the last knownposition of the objects(s) specified by the identifier(s) and(optionally) history of their movement

7


Chapter 4GPS API Methods

8


Chapter 5GPS API Methods Description

5 GPS API Methods Description

'set_position' Method The 'set_position' method is used to update the position of an object. Several objects and their GPS coordinates andtimestamps can be specified in one transaction.

'set_position' Request The 'set_position' method request specifies:

• the identifier of the object whose position is to be updated

• the geographic coordinates to be set for the specified object

• the time when the object was at the position defined by the coordinates

All method parameters are mandatory (if any mandatory parameter is missing, the corresponding error is returned).

The following table describes the ‘set_position' request parameters.

Name Required Type Description

authenticationelements

Yes

struct

authentication structure

data

Yes

struct

array of 'item' elements each corresponding to a single object whoseposition is to be defined

• 'item' Element of 'set_position' Request

Each 'item' element represents an object whose position is to be defined and contains the following mandatory elements:


id

Yes

string

case-sensitive object identifier; can bean object login, name, external ID, etc.

latitude

Yes

float

geographical latitude (GreenwichGeographical Coordinates in decimaldegrees)

longitude

Yes

float

geographical longitude (GreenwichGeographical Coordinates in decimaldegrees)

timestamp

Yes

DateTime

timestamp in the YYYY-MM-DDHH:MM:SS format

9



'set_position' Request Example <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:toatech:Positioning:1.0"> <SOAP-ENV:Body> <ns1:set_position> <now>2014-05-15T17:10:51+00:00</now> <login>soap</login> <company>in132</company> <auth_string>238165d8d5603c670cecfb6b4faeb698</auth_string> <data> <item> <id>22</id> <latitude>23.99</latitude> <longitude>32.5</longitude> <timestamp>2014-05-15T14:22:54</timestamp> </item> <item> <id>HARTWIG, Luis</id> <latitude>20.00</latitude> <longitude>32.5</longitude> <timestamp>2014-05-15T12:10:15</timestamp> </item> </data> </ns1:set_position> </SOAP-ENV:'data' ArrayBody> </SOAP-ENV:Envelope>

'set_position' Response If the transaction fails, a fault response is returned. Upon a successful transaction, the 'set_position' method returns thenumber of successfully updated objects.

The following table describes the 'set_position' response parameters.


return

int

number of updated objects

'set_position' Response Example <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:toatech:Positioning:1.0"> <SOAP-ENV:Body> <ns1:set_positionResponse> <return>2</return> </ns1:set_positionResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

10



'get_position' Method The 'get_position' method is used to retrieve GPS coordinates of the object(s) on the basis of object identifiers and timeframespecified.

'get_position' Request A 'get_position' request contains the following elements:


authentication elements

Yes

struct


ids

Yes

struct

array of 'item' elements each containing a case-sensitive object identifier; can be an object login, name,external ID, etc. At least one 'item' element is mandatory.

timefrom

Yes

DateTime

beginning of the search interval in the YYYY-MM-DDHH:MM:SS format

timeto

Yes

DateTime

end of the search interval in the YYYY-MM-DDHH:MM:SS format

history

No

bool

option defining whether the request should return thehistory of the object(s) movement (the list of coordinateswith the corerspondign timestamps) within the intervaldefined with the 'timefrom' and 'timeto' parameters default value: false

'get_position' Request Example <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:toatech:Positioning:1.0"> <SOAP-ENV:Body> <ns1:get_position> <now>2014-08-14T16:51:53Z</now> <login>soap</login> <company>in132</company> <auth_string>ef8c4c522657e55f928b128b8d259b97</auth_string> <ids> <item>1022</item> <item>1023</item> <item>1024</item> </ids> <timefrom>2012-02-14T00:00:01</timefrom> <timeto>2012-02-14T23:59:59</timeto>

11



<history>true</history> </ns1:get_position> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

'get_position' Response If the transaction fails, a fault response is returned. Upon a successful transaction, the 'get_position' response consists ofa 'return' element containing the GPS data of the objects specified in the request. The 'return' element is an array of 'item'elements each corresponding to a single object specified in the request.

The following table describes the 'get_position' response parameters.


id

string

object identifier

status

int

transaction status code for the object identified with the 'id' parameter. possible values: 0 – 'id' found, coordinates returned 1 – 'id' not found, no coordinates returned 2 – 'id' found, but no GPS coordinates correspond to the specified time frame. Nocoordinates returned

coordinates

struct

array of 0 or more 'item' elements each containing data on the GPS position of a singleobject

authenticationelements

struct


• 'item' Element of 'get_position' Response

Each 'item' element represents an object whose position is to be defined and contains the following mandatory elements:


latitude

float

geographical latitude (Greenwich Geographical Coordinates indecimal degrees)

longitude

float

geographical longitude (Greenwich Geographical Coordinates indecimal degrees)

timestamp

DateTime

timestamp in the YYYY-MM-DD HH:MM:SS format

The 'item' elements in the 'coordinates' array are sorted by the 'timestamp', so that later (newer) records are located higher.

12



'get_position' Response Examples <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:toatech:Positioning:1.0"> <SOAP-ENV:Body> <ns1:get_positionResponse> <return> <item> <id>12345</id> <status>1</status> <coordinates/> </item> <item> <id>12346</id> <status>1</status> <coordinates/> </item> </return> </ns1:get_positionResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

• 'get_position' Response Containing Objects Coordinates

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:toatech:Positioning:1.0"> <SOAP-ENV:Body> <ns1:get_positionResponse> <return> <item> <id>1022</id> <status>0</status> <coordinates> <item> <latitude>38.99</latitude> <longitude>31.2</longitude> <timestamp>2012-05-31T19:29:54Z</timestamp> </item> </coordinates> </item> <item> <id>1023</id> <status>0</status> <coordinates> <item> <latitude>23.99</latitude> <longitude>32.2</longitude> <timestamp>2012-05-31T19:29:54Z</timestamp> </item> </coordinates> </item> <item> <id>1024</id> <status>0</status> <coordinates> <item> <latitude>40.94</latitude> <longitude>33.2</longitude> <timestamp>2012-05-31T19:29:54Z</timestamp> </item> </coordinates>

13



</return> </ns1:get_positionResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

14


Chapter 6Fault Responses

6 Fault Responses

Fault Responses Upon transaction error Fault Responses are returned. Fault response contains a faultcode and faultstring of an errormessage.

Error Messages Each error message is either a SOAP Fault message, or an HTTP error, or a ResourceElement error. GPS Interface responsescan contain the following error messages:

Type Code Message Occurs When

HTTP error

404

Not Found

Request method is not POST (exceptwhen getting WSDL)

Server

Procedure 'X' not present

Method name is not 'get_position' or'set_position'

Server

SOAP-ERROR: Encoding:Violation of encoding rules

in the 'set_position' method, the valueof latitude or longitude is specifiedincorrectly

Client

Authentication failed

Invalid credentials are passed inrequest

Client

Wrong parameter format

Request format is invalid

Client

Invalid interval of time wasspecified

In the 'get_position' method, the valueof 'timeto' is less than 'timefrom'

Server

Database error

Server cannot connect to database orexecute query

Client

Invalid value of geographiccoordinate(s)

In the 'set_position' method,abs(latitude) > 90˚ or abs(longitude) >180˚

SOAP Fault

Client

Bad Request

Request is not valid XML

ResourceElement status

1

In the 'get_position' method, no datafound for the specified interval

15


Chapter 6Fault Responses

Fault Response Example

<?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>SOAP-ENV:Client</faultcode> <faultstring>Bad Request</faultstring> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

16

Integrating with GPS API Oracle Field Service Cloud · Integrating with GPS API Chapter 1...

Documents

Transcript of Integrating with GPS API Oracle Field Service Cloud · Integrating with GPS API Chapter 1...