Getting Started

This section will help you to get started quickly with the Work Management Web Services, by describing the key parts of a minimal sample program, Sample 1 , that uses the JobManagement service to create and then update a task within GeoManager.

The Sample 1 program is written in Java and is based upon the Apache Axis2 web services engine, using XMLBeans as the method of data binding. It is supplied in a self-contained directory called Sample1 , within the Sample_code zip file. For more information about generating a web service client using Apache Axis2, see Related documents.

This section also contains sample programs that assign and dispatch a task, retrieve task details, and close a task.

Note

Before using the services to develop client software that will be used in a live deployment, there are important concepts that you should understand. As this section describes a minimal sample program that is designed to help you to get up and running as quickly as possible, those concepts are not covered here. Please refer to the Concepts section before developing real-world applications that use the Work Management Web Services.

Sample 1: Creating and updating a task

Objective:

The Sample 1 program demonstrates how to use Apache Axis2 to call on to the GeoManager Web Services to create a task, retrieve the details of the newly created task, and then update it.

Prerequisites:

  • A user account for the GeoManager instance to which the web services are connected. The URL for the JobManagement service endpoint will be of the form https://<machine>/soapapi/JobManagementV6/v1 (where <machine> is the name or IP address of the web server that is running the service). For example, this could be:

    https://www.road.com/soapapi/JobManagementV6/v1

  • A Java 6 Development Kit, or better, and the source code files for the Sample 1 program. These are in the Sample_code zip file, and can be found here:

    <path>\Sample_code\Sample1

    Where <path> is the directory where you expanded the Sample_code zip file.

  • Apache Maven 2.2, in order to compile the source code.

  • To create a task, you must first set up organizational units. Organizational units are business-specific, and represent the way in which a business is hierarchically divided. For example, organizational units might be based upon location, line management, product, service, or project.

The code:

Open the file Sample1\src\main\java\com\trimble\mrm\ws\sample1\TaskWebServices.java. This is the main class responsible for calling the web service.

The first lines to note begin on line 40. This code constructs the URL for the GeoManager web service:

String baseURL = String.format("%s://%s", Constants.COMMS_PROTOCOL, inputArgs.getIPAddress());

String service = String.format("%s", Constants.JOB_MGT_SERVICE);

String url = baseURL + service;

The next section of importance is on line 42, which creates a new JobManagementStub object, passing in the URL for the JobManagement service endpoint:

JobManagementStub jobMgmtStub = new JobManagementStub( url );

Next, consider lines 55 to 60. These lines uses the construct the URL for the Token service, and then use the AuthMgr helper class to fetch an OAuth token:

String tokenService = String.format("%s", Constants.TOKEN_SERVICE);

String tokenURL = baseURL + tokenService;

AuthMgr authMgr = new AuthMgr(tokenURL);

String bearer = authMgr.getBearer(inputArgs.getUsername(), inputArgs.getPassword());

//Update the SOAP header

addAuthTokenToHeader(jobMgmtStub, bearer);

Note

The OAuth token that is returned by the Token service is added to the HTTP headers of subsequent API requests. See Security for more information.

Lines 68 and 69 instantiate a CreateTaskService object, and call its createTask method.

If you open the file Sample1\src\main\java\com\trimble\mrm\ws\sample1\createtask\CreateTaskService.java (which contains the implementation of the CreateTaskService class) and look at line 59, you will see the code that builds the XML for the CreateTaskRequest message:

CreateTaskRequestDocument createTaskReqDoc = createCreateTaskRequestDocument(orgUnitName);

The code on line 65 of the CreateTaskService.java file actually sends the CreateTaskRequest message to the service endpoint, and returns the response that it receives:

taskId = sendRequest(jobMgmtStub, createTaskReqDoc);

The code that gets the task’s details, and then updates it, follows a similar pattern.

Lines 81 and 82 of the TaskWebServices.java file instantiate a GetTaskDetailsService object and call its getTaskDetails method, which is defined in the file Sample1\src\main\java\com\trimble\mrm\ws\sample1\updatetask\GetTaskDetailsService.java .

Likewise, lines 92 and 93 of the TaskWebServices.java file instantiate an UpdateTaskService object and call its updateTask method, which is defined in the file Sample1\src\main\java\com\trimble\mrm\ws\sample1\updatetask\UpdateTaskService.java .

Running the sample

Use the Maven project to compile the source code. You can do this from the command line, by changing to the Sample1 directory and entering this command:

mvn clean compile package

Run the source code, passing in the following parameters:

  • Your GeoManager user name.
  • Your password.
  • The name of the organizational unit that you want to create the task for.

For example:

java -cp "target/*" com.trimble.mrm.ws.sample1.TaskWebServices user1 user1 orgA www.road.com

If you run the sample, the first part of the output that you see should be similar to this:

URL=https://10.122.91.91/soapapi/JobManagementV2/v1

------------------------------------------------------------------

------------------------------------------------------------------

Create Task Request Started

------------------------------------------------------------------

------------------------------------------------------------------

Generated request XML

<createTaskRequest xmlns="http://trimble.com/mrm/jobmanagement/servicetype/createtask/v1"
xmlns:v1="http://trimble.com/mrm/task/abstractions/task/v1"

xmlns:v11="http://trimble.com/mrm/task/abstractions/taskaddress/v1"

xmlns:v12="http://trimble.com/mrm/task/datatypes/address/v1" xmlns:v13="http://trimble.com/mrm/task/abstractions/taskcontact/v1"

xmlns:v14="http://trimble.com/mrm/framework/datatypes/reference/v1" xmlns:v15="http://trimble.com/mrm/task/datatypes/taskdetails/v1" xmlns:v16="http://trimble.com/mrm/task/abstractions/capability/v1"

xmlns:v17="http://trimble.com/mrm/task/abstractions/customfield/v1">

   <createTask>

      <v1:commitmentType>C</v1:commitmentType>

      <v1:timezoneName>Europe/London</v1:timezoneName>

      <v1:taskAddressList>

         <v11:address>

            <v11:location>

               <v11:latitude>

                  <v12:value>52.047405</v12:value>

               </v11:latitude>

               <v11:longitude>

                  <v12:value>1.158112</v12:value>

               </v11:longitude>

            </v11:location>

            <v11:address>

               <v11:addressNo>1</v11:addressNo>

               <v11:addressType>Work</v11:addressType>

               <v11:crossStreet>Bath Street</v11:crossStreet>

               <v11:city>Ipswich</v11:city>

               <v11:zipCode>IP2 8SD</v11:zipCode>

               <v11:state>Suffolk</v11:state>

               <v11:country>UNITED KINGDOM</v11:country>

               <v11:countryCode>GB</v11:countryCode>

               <v11:geofenceRadius>100</v11:geofenceRadius>

            </v11:address>

         </v11:address>

      </v1:taskAddressList>

      <v1:taskContactList>

         <v13:contact>

            <v13:contactSeqNo>1</v13:contactSeqNo>

            <v13:contactName>James Sutherland</v13:contactName>

            <v13:contactType>Office Phone</v13:contactType>

            <v13:contactDetails>480 961 6468</v13:contactDetails>

         </v13:contact>

         <v13:contact>

            <v13:contactSeqNo>2</v13:contactSeqNo>

            <v13:contactName>James Sutherland</v13:contactName>

            <v13:contactType>e-mail</v13:contactType>

            <v13:contactDetails>James_Sutherland@example.com</v13:contactDetails>

         </v13:contact>

      </v1:taskContactList>

      <v1:latestStartDateTime>

       <v14:value>2013-11-05T13:52:29.466Z</v14:value>

      </v1:latestStartDateTime>

      <v1:commitmentDateTime>

       <v14:value>2013-11-05T15:52:29.466Z</v14:value>

      </v1:commitmentDateTime>

      <v1:externalTaskReference>Task0001</v1:externalTaskReference>

      <v1:orgUnitName>Celestra_US</v1:orgUnitName>

      <v1:importanceClass>

         <v15:value>1</v15:value>

      </v1:importanceClass>

      <v1:taskType>Install</v1:taskType>

      <v1:capabilityList>

         <v16:capability>INSTALL</v16:capability>

         <v16:capability>SPECIAL</v16:capability>

      </v1:capabilityList>

      <v1:customFieldList>

         <v17:customField>

            <v17:label>CUSTOM LABEL 001</v17:label>

            <v17:value>SPECIAL</v17:value>

         </v17:customField>

         <v17:customField>

            <v17:label>CUSTOM LABEL 002</v17:label>

            <v17:value>SERVICE</v17:value>

         </v17:customField>

         <v17:customField>

            <v17:label>CUSTOM LABEL 003</v17:label>

            <v17:value>SPECIAL</v17:value>

         </v17:customField>

         <v17:customField>

            <v17:label>CUSTOM LABEL 004</v17:label>

            <v17:value>SERVICE</v17:value>

         </v17:customField>

      </v1:customFieldList>

   </createTask>

</createTaskRequest>



Task created has ID '14730'. Time taken '12,352' milliseconds.

The first part of the snippet shows you the XML that was generated. The last line of the snippet shows you the task ID of the newly-created task, and tells you how many milliseconds the request took to process.

Sample 2: Assigning and dispatching a task

Objective:

The Sample 2 program follows on from Sample 1 by demonstrating how to use Apache Axis2 to call on to the GeoManager Web Services to assign a task to an employee, and then to dispatch it.

Prerequisites:

  • A user account for the GeoManager instance to which the web services are connected.

    The URL for the JobManagement and ScheduleManagement service endpoints will be of the form https://<machine>/soapapi/<service>/v1 (where <machine> is the name or IP address of the web server that is running the services, and <service> is the name of one of the services). For example, this could be:

    https://www.road.com/soapapi/JobManagementV6/v1

    Or:

    https://www.road.com/soapapi/WSScheduleManagement/v1

  • A Java 6 Development Kit, or better, and the source code files for the Sample 2 program. These are in the Sample_code zip file, and can be found here:

    <path>\Sample_code\Sample2

    Where <path> is the directory where you expanded the zip file.

  • Apache Maven 2.2, in order to compile the source code.

  • A task ID and an employee ID. A task ID can be acquired by running the Sample 1 program (see Sample 1: Creating and updating a task), and an employee ID can be retrieved from the GeoManager UI.

The code:

Open the file Sample2\src\main\java\com\trimble\mrm\ws\sample2\Sample2.java . This is the main class responsible for calling the web service.

The first lines to note begin on line 57. This code constructs the URL for the GeoManager web service:

String baseURL = String.format("%s://%s", Constants.COMMS_PROTOCOL, inputArgs.getIPAddress());

String service = String.format("%s", Constants.SCHEDULE_MGT_SERVICE);

String url = baseURL + service;

The next important line is line 69, which creates a new WSScheduleManagementServiceStub object, passing in the URL for the WSScheduleManagementService service endpoints:

WSScheduleManagementServiceStub schMgmtStub = new WSScheduleManagementServiceStub(url);

Next, consider lines 72 to 77. These lines uses the construct the URL for the Token service, and then use the AuthMgr helper class to fetch an OAuth token:

String tokenService = String.format("%s", Constants.TOKEN_SERVICE);

String tokenURL = baseURL + tokenService;

AuthMgr authMgr = new AuthMgr(tokenURL);

String bearer = authMgr.getBearer(inputArgs.getUsername(), inputArgs.getPassword());

//Update the SOAP header

addAuthTokenToHeader(schMgmtStub, bearer);

Note

The OAuth token that is returned by the Token service is added to the HTTP headers of subsequent API requests. See Security for more information.

Now consider line 82. This line creates an Axis2 web service request XML document, which will assign a task to an employee:

AssignTaskRequestDocument assignReqDoc = createAssignTaskRequestDocument(inputArgs.getTaskId(), inputArgs.getEmployeeId());

Line 88 sends the request to the server for processing:

sendAssignRequest(schMgmtStub, assignReqDoc)

If the task is assigned successfully, line 90 creates a request to dispatch the assigned task:

DispatchTaskRequestDocument dispReqDoc = createDispatchTaskRequestDocument(inputArgs.getTaskId());

Finally, line 95 sends the dispatch request XML message to the server for processing:

sendDispRequest(schMgmtStub, dispReqDoc);

Running the sample

Use the Maven project to compile the source code. You can do this from the command line, by changing to the Sample2 directory and entering this command:

mvn clean compile package

Run the source code, passing in the following parameters:

  • Your GeoManager user name.
  • Your password.
  • The ID of the task that you want to assign and dispatch (see Sample 1: Creating and updating a task for information about creating a task).
  • The ID of the employee that you want to assign the task to.

For example:

java -cp "target/*" com.trimble.mrm.ws.sample2.Sample2 user1 user1 482298 employeeA www.road.com

If you run the sample you should see output that is similar to this, which shows the request XML that is generated to assign the task:

<assignTaskRequest xmlns="http://trimble.com/mrm/schedule/servicetype/assigndetails/v1"

xmlns:v1="http://trimble.com/mrm/schedule/abstractions/assigntaskdetails/v1" xmlns:v11="http://trimble.com/mrm/framework/datatypes/reference/v1">

   <assignTaskDetails>

      <v1:taskId>14731</v1:taskId>

      <v1:employeeId>21</v1:employeeId>

      <v1:scheduleOnDate>

         <v11:value>2011-06-07T14:46:43.369+01:00</v11:value>

      </v1:scheduleOnDate>

      <v1:notes>Assigned this task from WS Client</v1:notes>

   </assignTaskDetails>

</assignTaskRequest>

The request XML should be followed by output similar to this, which shows that the task was successfully assigned:

Task successfully assigned'. Time taken '6,527' milliseconds.

Note

If the task could not be assigned because it is not in a valid state, you will see an error message instead.

Next, you should see the following XML that has been generated for the request to dispatch the task. It will look similar to this:

<taskId xmlns="http://trimble.com/mrm/schedule/abstractions/dispatchtaskdetails/v1">14731</taskId>

Finally, you should see output similar to this, if the task was successfully dispatched:

Task successfully dispatched'. Time taken '531' milliseconds.

Sample 3: Retrieving task details

Objective:

Sample 3 shows you how to use .NET 4 Windows Communication Foundation to call on to the GeoManager Web Services to retrieve extended details for a task.

Prerequisites:

  • A user account for the GeoManager instance to which the web services are connected.

    The URL for the JobManagement and ScheduleManagement service endpoints will be of the form https://<machine>/soapapi/<service>/v1 (where <machine> is the name or IP address of the web server that is running the services, and <service> is the name of one of the services). For example, this could be:

    https://www.road.com/soapapi/JobManagementV6/v1

    Or:

    https://www.road.com/soapapi/WSScheduleManagement/v1

  • Visual Studio 2010 or above

  • The external task reference of a task

The code:

Open the project Sample3\Sample3.sln , and then open the file Sample3\TestHarness\Sample3.cs .

The first thing to note is that, on line 25 of Sample3.cs , an AuthMgr helper object is use to obtain an OAuth token. The code that actually requests the token can be seen in the file Sample3\TestHarness\AuthMgr.cs , from line 36:

String uri = ConfigurationSettings.AppSettings&lsqb;"AuthenticationURI"&rsqb; + "&sol;tokens";

HttpWebRequest req = WebRequest.Create(uri) as HttpWebRequest;

req.KeepAlive = false;

req.Method = "POST";

req.ContentType = "application&sol;json";

String requestStr = buildIdentity(username, password);

req.ContentLength = requestStr.Length;

Stream PostData = req.GetRequestStream();

byte&lsqb;&rsqb; buffer = Encoding.ASCII.GetBytes(requestStr);

PostData.Write(buffer, 0, buffer.Length);

PostData.Close();

HttpWebResponse resp = req.GetResponse() as HttpWebResponse;

Encoding enc = System.Text.Encoding.GetEncoding(1252);

StreamReader loResponseStream =

new StreamReader(resp.GetResponseStream(), enc);

string Response = loResponseStream.ReadToEnd();

loResponseStream.Close();

resp.Close();

token = getToken(Response);

The sample project uses the WSJobManagementV6.wsdl file to create a service reference called Proxy .

The sample then uses the generated Proxy classes to create a JobManagementPortTypeClient object.

The Proxy classes are then used to create a GetTaskDetailsRequest object, which contains a valid external task reference for a task in GeoManager.

This object is passed to the GetTaskDetails method of the JobMangementPortTypeClient object, which makes the server call and returns a response object containing the extended details of the requested task.

The Proxy classes are configured in the project’s app.config file.

Running the sample

  1. In the project explorer, right-click the Test Harness project and select Properties . The Project Properties window appears.
  2. In the Project Properties window, click the Debug tab.
  3. Ensure that the Command line arguments box contains the correct information.
  4. On the toolbar, click Save .
  5. Run the project. Once the program has finished running, a message box displaying the ID of the task that you requested will be displayed.

Sample 4: Closing a task

Objective:

The Sample 4 program demonstrates how to use Apache Axis2 to call on to the GeoManager Web Services to close a task.

Prerequisites:

  • A user account for the GeoManager instance to which the web services are connected.

    The URL for the JobManagement and ScheduleManagement service endpoints will be of the form https://<machine>/soapapi/<service>/v1 (where <machine> is the name or IP address of the web server that is running the services, and <service> is the name of one of the services). For example, this could be:

    https://www.road.com/soapapi/JobManagementV6/v1

    Or:

    https://www.road.com/soapapi/WSScheduleManagement/v1

  • A Java 6 Development Kit, or better, and the source code files for the Sample 4 program. These are in the Sample_code zip file, and can be found here:

    <path>\Sample_code\Sample4

    Where <path> is the directory where you expanded the zip file.

  • Apache Maven 2.2, in order to compile the source code.

  • A task ID. This can be acquired by running the Sample 1 program (see Sample 1: Creating and updating a task).

The code:

Open the file Sample4\src\main\java\com\trimble\mrm\ws\sample4\Sample4.java . This is the main class responsible for calling the web service.

The first lines to note begin on line 53. This code constructs the URL for the GeoManager web service:

String baseURL = String.format("%s://%s", Constants.COMMS_PROTOCOL, inputArgs.getIPAddress());

String service = String.format("%s", Constants.JOB_MGT_SERVICE);

String url = baseURL + service;

The next important line is line 65, which creates a new JobManagementStub object, passing in the URL for the JobManagement service endpoints:

JobManagementStub jobMgmtStub = new JobManagementStub( url );

Next, consider lines 68 to 73. These lines uses the construct the URL for the Token service, and then use the AuthMgr helper class to fetch an OAuth token:

String tokenService = String.format("%s", Constants.TOKEN_SERVICE);

String tokenURL = baseURL + tokenService;

AuthMgr authMgr = new AuthMgr(tokenURL);

String bearer = authMgr.getBearer(inputArgs.getUsername(), inputArgs.getPassword());

//Update the SOAP header

addAuthTokenToHeaderjobMgmtStub, bearer);

Note

The OAuth token that is returned by the Token service is added to the HTTP headers of subsequent API requests. See Security for more information.

Now consider line 78. This line creates an Axis2 web service request XML document, which will close a task:

CloseTaskRequestDocument closeTaskReqDoc = createCloseTaskRequestDocument(inputArgs.getExternalTaskRef(), inputArgs.getTaskId(), inputArgs.getEmployeeId(), inputArgs.getResourceId(), inputArgs.getResourceName());

Line 84 sends the request to the server for processing:

sendRequest(jobMgmtStub, closeTaskReqDoc);

Running the sample

Use the Maven project to compile the source code. You can do this from the command line, by changing to the Sample4 directory and entering this command:

mvn clean compile package

Run the source code, passing in the following parameters:

  • Your GeoManager user name.
  • Your password.
  • The ID of the task that you want to close (see Sample 1: Creating and updating a task for information about creating a task).
  • The ID of the employee that is closing the task.

For example:

java -cp "target/*" com.trimble.mrm.ws.sample4.Sample4 user1 user1 482298 employeeA www.road.com

If you run the sample you should see output that is similar to this, which shows the request XML that is generated to close the task:

<closeTaskRequest xmlns="http://trimble.com/mrm/jobmanagement/servicetype/closetask/v1"

xmlns:v1="http://trimble.com/mrm/task/abstractions/task/v1" xmlns:v11="http://trimble.com/mrm/task/abstractions/tasktimedetails/v1" xmlns:v12="http://trimble.com/mrm/framework/datatypes/reference/v1">

   <closeTask>

      <v1:taskId>28624</v1:taskId>

      <v1:employeeId>PTS_005</v1:employeeId>

      <v1:notes>Example task closure notes.</v1:notes>

      <v1:completionTimeDetailsList>

         <v11:completionTimeDetails>

          <v11:timeType>TT1</v11:timeType>

          <v11:completionDateTime>

           <v12:value>2011-10-19T09:35:54.671+01:00</v12:value>

          </v11:completionDateTime>

         </v11:completionTimeDetails>

         <v11:completionTimeDetails>

          <v11:timeType>TT2</v11:timeType>

          <v11:completionDateTime>

           <v12:value>2011-10-19T09:35:54.718+01:00</v12:value>

          </v11:completionDateTime>

         </v11:completionTimeDetails>

      </v1:completionTimeDetailsList>

   </closeTask>

</closeTaskRequest>

The request XML should be followed by output similar to this, which shows that the task was successfully closed:

Task closed 'successfully'. Time taken '7,062' milliseconds.