Content

Query Definitions

In the Object Structure application, you can create predefined query definitions for a JSON resource that are then available from the API as saved queries. These definitions make it easier to access specific resource data through API since the Where condition of the query is predefined and does not need to be provided in the request. You can create a query definition by selecting the Query Definition action in the Object Structure application and specifying a definition type. A query can have one of the following types:

• Appclause is sourced from a saved query of an application.
• Method is sourced from an annotated method name within an object structure definition class.
• Osclause is similar to the Where clause in an application List tab.
• Script specifies that a predefined automation script is used to run a query.

Application Query Clause (appclause) means that the query is sourced from a Public Saved Query of an application. For this type, you specify the application name and an existing saved query for that application.

The following example demonstrates how to query for assets with an Application query:
//localhost/maximo/oslc/os/mxasset?_lean=1&savedQuery=ITSTOCK

SavedQueryis the query parameter name and the value, ITSTOCK,is the query name

If the object structure has an authorized application configured, the public saved queries for that application are available to use with the object structure by default. Registration of those queries (in the Query Definition dialog) are not required.

Since not all object structures have corresponding applications, the selection of an application when configuring a query does not restrict which application queries are selectable. The selection of an application and query must have a logical connection to the resource. For example, you can configure a query from the Purchase Order application to be used on a work order JSON resource but the query will not run properly because the objects do not align.

Query Method (method) means that the query is sourced from an annotated method name within the object structure's definition class. For this type, you select the method, provide a description for the query, and flag whether the query is public or not. Method annotations are formatted in the following manner:
@PreparedQuery(//maximo.nextgen.asset#publicAssets)

This option would be used if a method was implemented for query purposes. There are no default query methods provided, this would be a custom code implementation.

Object Structure Query Clause (osclause) means that the query where clause is defined in this query definition. For this type, you enter a Where clause, provide a name and description for the query, and flag whether the query is public or not. The Where clause format is similar to a Where clause that is used in an application List tab. Public queries are available to everyone to use. Non-public queries are only available to the query owner.

Query Script (script) means the query is run with a predefined automation script. This configuration allows for more complex queries than are normally supported by a Query clause. For this definition, you select a script name and flag whether the query is public or not. Public queries are available to everyone to use. Non-public queries are only available to the query owner.

The creation of a script for an object structure can be defined as a query clause. When you define a script as a query clause, the script can be configured as an object structure query for use with the JSON API.



Any query that is configured for an object structure is included in the API metadata for that resource and can be accessed by using the API metadata URL (//localhost/maximo/oslc/apimeta/object structure name ). For example, the mxasset resource URL would be //localhost/maximo/oslc/apimeta/mxasset.

Within the API metadata for the object structure there will be a queryCapability for each query. The following example is for a query name of ITSTOCK and a description (title) of test.

"queryCapability":
[
{
"title": "test",
"ispublic": true,
"name": "ITSTOCK",
"href": "http://localhost/maximo/oslc/os/mxasset?savedQuery=ITSTOCK"
}
],

Action Associations

With action associations, you can associate a defined action to an object structure (JSON Resource) and configure a signature option with the action. The action association type determines how the action is defined for the object structure. An action can have one of following types:


• Method actions can be defined by using a service method that is properly annotated.
• Script associations specify that an action use an object structure automation script to run.
• Workflow associations identify a workflow process to run as an action.
• System associations identify a system function to run as an action.

The execution of an action passes the MBO/MBOSet handle of the MBO resource (identified in the URL) to the Action. For example, when the URL identifies a work order, the handle of the work order would be passed to the workflow process. Normally the handle contains a single MBO but if the Collection Action flag is selected, the action can support a MBOSet. Any action requires the HTTP header, x-method-override, to be provided with a value of PATCH.

Method actions are defined by an annotated method in the Application Service tied to the root MBO on the object structure. For example, if the MXASSET object structure is being configured, the root MBO is ASSET and the service that is tied to the ASSET MBO is the asset service. In this case, any annotated method in the Asset service would be available to use as an action.
The API can use the action in the following ways:

• If the action is not registered with the object structure it can be invoked with this URL format:

//localhost/maximo/oslc/os/mxwo/_Qk9TMS9CRURGT1JEQQ--?action=wsmethod:changeStatus
This work order URL identifies a work order resource, an action type of method, and the method name of changeStatus. This approach does not support any authorization.

• To provide authorization for this action through the API (limit use of the Action through the API) you would have to register the action with the object structure resource and assign a security signature option. To execute a registered action, you would use the following URL format:

//localhost/maximo/oslc/os/mxwo/_Qk9TMS9CRURGT1JEQQ--?action=mychangeStatus

Once an action (changeStatus) is registered to an object structure, the access through the unsecured format (action=method:changeStatus) is based on the configuration of registered action.

Script actions are defined using an object structure automation script. When this action type is selected, you would select an object structure script to defined for action processing. Defining object structure for action processing allows the script to be configured as an object structure query for use with the JSON API.



The API can invoke the action in two ways:

• If the action is not registered with the object structure, it can be invoked using this URL format:

//localhost/maximo/oslc/os/mxwo/_Qk9TMS9CRURGT1JEQQ--?action=script
This work order URL, identifies a work order resource, an action type of script, and the script name of OSACTION.MXWO.MYACTION. This approach does not support any authorization.

• To provide authorization for this action through the API, you would have to register the action with the object structure resource and assigning a security signature option. To execute a registered action, you would use the following URL format:

//localhost/maximo/oslc/os/mxwo/_Qk9TMS9CRURGT1JEQQ--?action=myscriptaction

Once an action (OSACTION.MXWO.MYACTION) is registered to an object structure, access through the unsecured format (action=script:myscriptaction) is based on the configuration of registered action.

Workflow actions identify a workflow process to execute. When this action type is specified, you select an existing workflow process that is tied to the root object of the object structure. The API can invoke the action in two ways:

• If the action is not registered with the object structure it can be invoked using this URL format:

//localhost/maximo/oslc/os/mxwo/_Qk9TMS9CRURGT1JEQQ--?action=workflow:WOAPPR
This work order URL identifies a work order resource, an action type of workflow, and the workflow process name of WOAPPR. This approach does not support any authorization.

• To provide authorization for this action through the API (limit use of the action through the API) you would register the action with the object structure resource and assign a security signature option. To execute a registered action, the following URL format would be used:

//localhost/maximo/oslc/os/mxwo/_Qk9TMS9CRURGT1JEQQ--?action=mywoappr

Once an action (WOAPPR) is registered to an object structure, the access through the unsecured format (action=workflow:WOAPPR) is based on the configuration of registered action.

System actions identify a system function to run. When this type of action is specified, you select an existing system function available for the specified object structure. Setting a bookmark or adding an image are examples of system functions. Some functions that are user interface oriented, such as a setting a bookmark, are supported but require the assignment of an application to the object structure.

The API can invoke the action in two ways:

• If the action is not registered with the object structure it can be invoked using the following URL format:

//localhost/maximo/oslc/os/mxwo/_Qk9TMS9CRURGT1JEQQ--?action=system:BOOKMARK
This work order URL, identifies a work order resource, an action type of system, and the system function of BOOKMARK. This approach does not support any authorization.

• To provide authorization for this action through the API, you would register the action with the object structure resource and assign a security signature option. To execute a registered action, the following URL format would be used:

//localhost/maximo/oslc/os/mxwo/_Qk9TMS9CRURGT1JEQQ--?action=mybookmark

Once an action (BOOKMARK) is registered to an object structure, access through the unsecured format (action=system:BOOKMARK) is based on the configuration of registered action.

Once the action implementation is provided, you can select a signature option to assign to the action so that explicit authorization can be configured for the action. The signature option definition would occur in the Application Designer application for the authorized application of the selected object structure. When a new action is implemented, a signature option can be created for it and then assigned to the action in this dialog. Once the signature option is created, you can grant access to the signature option in the Security Groups application under the applicable application just like an application signature option.

The look-up of the signature option displays all the existing signature options for the authorized application. Under some conditions it may make sense to use an existing signature option rather than create a new signature option for the application.

A new dialog, Action Definition, will be made available in the Object Structure application to associate an API action to a signature option for an object structure. This action is available only to object structures that have a Consumed By value of INTEGRATION or OSLC. In order to assign a signature option, the object structure must have an authorized application assigned to it.