Completions Search - AcceleratorKMS - Version 5.0 - Help - Hexagon

AcceleratorKMS API Guide

Language
English
Product
AcceleratorKMS
Search by Category
Help
AcceleratorKMS Version
5.1

Use the Completions Search API to pull data on completions, such as users, dates, data collection values, and comments.

URL

https://AcceleratorKMS_URL/api/Completions/Search

Where:

AcceleratorKMS_URL is replaced with your AcceleratorKMS instance.

HTTP Verb

Make an HTTP POST request using the following header and parameters.

Header

Key

Value

Description

Authorization

bearer <token>

Actual token value acquired from the authentication step

Content-Type

application/json

Designates the POST’s content response as JSON format

Parameters

At least one search parameter is required for the request to proceed.

Parameters

Type

Description

SearchTerm

String

Represents the content title, completion number, or work order number

Domain

String

Identifier (GUID) of the domain node

LimitSearchResults

Integer

Represents the number of results to return

ContentType

String

Name of content type, for example: "Procedure"

Status

String

Can be "Completed", "Cancelled", "Partially Completed", or "Queued"

ForWorkflows

Integer

Optional parameter to include completions for workflows.

  • 0 = JSON includes completions for workflows

  • 1 = No workflow completions included (default)

  • -1 = All completions are included

CreatedDateMin

Date

Earliest completion start date; format is: YYYY-MM-DD Example: 2019-12-31

Defaults to six months before today, if no other date range filters set

CreatedDateMax

Date

Latest completion start date; format is: YYYY-MM-DD

CompletedDateMin

Date

Earliest completed date; format is: YYYY-MM-DD

CompletedDateMax

Date

Latest completed date; format is: YYYY-MM-DD

IncludeCommentDetails

Boolean

Provides comment details including type, label, user, time stamp, and comment. Default is False; must be set to True to be included in JSON response.

IncludeDataCollectionDetails

Boolean

Provides data collection details including key definition, input value, user, and time stamp. Default is False; must be set to True to be included in JSON response.

ModifiedDateMin

Date

Earliest completion modified date; format is: YYYY-MM-DD

ModifiedDateMax

Date

Latest completion modified date; format is: YYYY-MM-DD

Source

Integer

Input parameter to search by source indicator. Can be 0, 1, 2 and -1.

  • 0 = web application

  • 1 = create completion API

  • 2 = offline mobile application sync

  • -1 = completions created by the web application or offline mobile application sync in versions prior to 5.0

Result Parameters

Parameter

Description

ContentProperties

Container for sub-values describing Property metadata assigned to the content associated with the Completion.

ContentProperties > Name

Text title of Property name on content associated with the Completion.

ContentProperties > Value

Value name(s) applied to given Property name.

DataCollections

Container for sub-values describing Data Collection attributes associated with the Completion.

DataCollections > Key > Id

Unique identifier (GUID) of Data Collection key.

DataCollections > Key > Name

Text title of the Data Collection key.

DataCollections > Key > DataType

Type of Data Collection key:

  • 0 = Text

  • 1 = Numeric

  • 2 = Date/Time

  • 3 = Single select list

  • 4 = Multi select list

DataCollections > Key > Units

Text name of units associated with the Data Collection key, if defined.

DataCollections > Key > Options > Id

For Single select list (Data Type 3) or Multi select list (Data Type 4) Data Collection key, Unique identifier (GUID) of the selectable option in the list.

DataCollections > Key > Options > Names

For Single select list (Data Type 3) or Multi select list (Data Type 4) Data Collection key, text title of the selectable option in the list.

Entries are separated by language with a culture code attribute.

DataCollections > Value

For Data Type 0, 1, or 2, this is the value entered by the user in the Completion. For Data Type 3 or 4, this is a container to be expanded to another layer of attributes.

DataCollections > Value > Values > Id

For Single select list (Data Type 3) or Multi select list (Data Type 4) Data Collection key, Unique identifier (GUID) of the list option selected/entered by the user in the Completion.

DataCollections > Value > Values > Name

For Single select list (Data Type 3) or Multi select list (Data Type 4) Data Collection key, text title of the list option selected/entered by the user in the completion.

DataCollections > Value > Key

Unique identifier (GUID) of Data Collection key.

DataCollections > TimeStamp

Date and Time (YYYY-MM-DD T HH:MM:SS - UTC Timezone) the Data Collection value was entered in the Completion.

ClassificationFullPath

Full Domain path assigned to the content associated with the Completion. Domain levels are separated by ">".

AssetSerialNumber

Text - Asset Serial Number

CancelledByUser

For Completion in "Cancelled" status, AKMS username of the user who clicked Cancel in the Completion.

Comments > Statement

Container for values describing the statement attributes for which the user entered a comment in the completion.

Comments > Statement > Text

Culture code and the text of the statement for which the user entered a comment in the Completion.

Comments > Statement > Id

Unique identifier (GUID) of the statement for which the user entered a comment in the Completion

Comments > Statement > ItemId

Unique identifier (GUID) of the document's item for which a comment was entered by the user in the Completion.

Comments > Comment > Entries

Container for sub-values describing Comments attributes entered by users

Comments > Comment > Entries > Text

Text comment entered by user in the Completion.

Comments > Comment > Entries > Labels

For Comment Type that has one or more input label(s) configured, this defines the label text.

Comments > Comment > Entries > Index

This defines the index of the comment type input label.

Comments > Comment Type

Container for sub-values describing Comment Type attributes selected by users associated with the Completion.

Comments > CommentType > Id

Unique identifier (GUID) of Comment Type selected by user for the entered Comment.

Comments > Comment Type > Names

Text Title of Comment Type selected by user for the entered Comment.

Comments > User

Container for sub-values describing user attributes associated with the Completion.

Comments > User > Username

AcceleratorKMS System login username of user who entered Comment.

Comments > User > Name

Name of user who entered comment.

Comments > User > Email

Email of user who entered Comment.

Comments > TimeStamp

Date and Time (YYYY-MM-DD T HH:MM:SS - UTC Timezone) the Comment was entered in the Completion (when user clicks Save comment).

Comments > Id

Unique identifier (GUID) for the comment entered by the user in the Completion.

Comments > Attachments

Container for sub-values describing Attachments attributes entered by users associated with the Completion.

Comments > Attachments > Filename

Defines attachment filename with extension.

Comments > Attachments > Title

Text title of the attachment

ModifiedDate

Date and Time (YYYY-MM-DD T HH:MM:SS - UTC Timezone) the completion was last modified.

Source

Indicates source of completion creation:

  • 0 = web application

  • 1 = create completion API

  • 2 = offline mobile application sync

  • -1 = completions created by the web application or offline mobile application sync in versions prior to 5.0

Id

Unique identifier (GUID) for the Completion.

ContentId

Unique identifier (GUID) for the content associated with the Completion.

ClassificationId

Unique identifier (GUID) for the content associated with the Completion.

Title

Text title of the content at the time the Completion was started.

Version

Version number of the content at the time the Completion was started.

Status

Status of the Completion at the time of querying the Completion History API. Defined statuses:

  • Cancelled - Completion was Cancelled.

  • Completed - Completion was Competed or Overridden Complete.

  • Partially Completed - Completion has started and has at least one statement with completed status in the su. The Completion is still open and has not yet been Completed or Overridden Complete.

  • Queued - Completion has been created but no statements have queued in the Completion. The Completion is still open and has not yet been Completed or Overridden Complete.

CreatedDate

Date and Time (YYYY-MM-DD T HH:MM:SS - UTC Timezone) the Completion was Created (when user clicks Start New Completion and a unique Completion number is created.)

CompletedDate

Date and Time (YYYY-MM-DD T HH:MM:SS - UTC Timezone) the Completion was Completed or Overridden Complete (when user clicks Complete in the Completion and the Completion changes status to Completed.)

CancelledDate

Date and Time (YYYY-MM-DD T HH:MM:SS - UTC Timezone) the Completion was Cancelled (when user clicks Cancel in the Completion and the Completion changes status to Cancelled.)

CanCompletionBeCancelled

Boolean - True/false - Indicates if the Completion can be cancelled.

WorkOrder

Optional text from Work Order field in Completion.

Work Order field may be named differently in AcceleratorKMS at Content Type Administration. Regardless of the Work Order label name configured in AcceleratorKMS, the Item name passed through Completion History API will be WorkOrder. The character limit in this field is <= 255 characters.

CompletionNumber

Unique Completion ID (not a GUID) for the Completion displayed in AcceleratorKMS (YYYY-MM-four digit sequential number)

SkippedSteps

For any steps in the Completion with status Skipped by the user, the individual step number for each skipped step. Skipped step numbers are separated by ",".

TotalNumOfSteps

Aggregated number of completable steps available for status in a Completion.

If branches are used in the content, then only substeps under the selected branch decision are counted towards the total number of steps.

TotalNumOfStepsCompleted

Aggregate number of completable steps that have been checked complete by the user.

AssignedUsers

Container for sub-values describing users who are currently assigned to the completion.

AssignedUsers > User > Username

AcceleratorKMS System login username of user assigned to the completion.

AssignedUsers > User > Name

Name of user assigned to the completion.

AssignedUsers > User > Email

Email of user assigned to the completion.

AssignedUsers > User > Culture

Returns Default User Language culture code.

AssignedUsers > User > TwoFactorRequired

Boolean, Indicates if the user's two factor authentication is required.

AssignedUsers > Role > Id

Unique identifier (GUID) for the assigned user's role.

AssignedUsers > Role > Name

Text Title of the assigned user's role.

AssignedUsers > Role > Description

Text description of the assigned user's role.

AssignedUsers > Role > IconHref

Null, Not Returned

AssignedUsers > Role > Abbreviation

Abbreviation of the assigned user's role.

AssignedUsers > Role > Index

Int - Not Returned

AssignedUsers > Role > Locked

Boolean, Returns the user status (True/False)

AssignedUsers > Role > Selected

Not returned

AssignedUsers > Role > AllowedOperations

Not returned

AssignedUsers > Role > Names

Multilingual - Text Title of the assigned user's role.

AssignedUsers > Role > Abbreviations

Multilingual - Abbreviation of the assigned user's role.

AssignedUsers > Role > Descriptions

Multilingual - Text Description of the assigned user's role.

AssignedUsers > Role > CultureCode

Return active language culture code

AssignedUsers > NumOfSteps

Aggregate number of completable steps associated with the role of the assigned user in the completion.

AssignedUsers > NumOfStepsCompleted

Aggregate number of steps with complete status associated with the role of the assigned user in the completion.

AssignedUsers > isActive

Boolean, defines User Status is Active/Inactive

HasComments

"TRUE" for a Completion that has one or more comments entered. "FALSE" for a completion that has no comments entered.

HasDataCaptured

"TRUE" for a Completion that has one or more Data Collection Keys with a value entered by the user. "FALSE" for a completion that has no value(s) entered for Data Collection Keys.

AssetId

For content generated from an Asset Template, this is the unique identification (GUID) for the associated Asset Profile.

AssetTypeName

For content generated from an Asset Template, this is the title of the associated Asset Profile.

ParentCompletion

Not returned

Although the field exists in the existing model, it either appears empty or is not included in the API response. This is intentional and indicates that the field should be disregarded, as it won't contain any meaningful data.

CompletionTaskParent

Includes details about the task to which the completion belong, when ForWorkflow is "TRUE", otherwise null when ForWorkflow is "FALSE.

  • "TRUE" for completion that belongs to a workflow task.

  • "FALSE" for a completion that does not relate to a workflow task.

ForWorkflows

Determines if completions required on workflow tasks are included in the results. Possible values are:

  • -1 = All completions, including workflow completions, are in the results

  • 0 = Only workflow completions are in the results

  • 1 = Exclude workflow completions from results; this is the default if not set

Sample Query

{"SearchTerm":"EVAP123 - Evaporator - Shutdown","IncludeDataCollectionDetails":true, "IncludeCommentDetails":true, "LimitSearchResults":2}

Sample Response (JSON)

When "Classification" is seen in response parameters, it is referring to the domain within AcceleratorKMS.

"ContentProperties": [

{

"Name": "Criticality",

"Value": "2-Medium"

}

],

"DataCollections": [

{

"Statement": {

"Texts": {

"en-CA": "<p><strong>RECORD</strong> level in holding tank.</p>"

},

"Id": "999e4551-0fc3-4e26-9159-98bfa69e797b",

"ItemId": "88362cf2-ced3-4383-bf8f-52ff1187ade0"

},

"Key": {

"Id": "2a7f022b-554c-4938-pkt3-bb3f1cefd2be",

"Name": "levelShutdown",

"DataType": 1,

"Units": "litres",

"Options": null,

"HasScanner": false

},

"Value": "500",

"TimeStamp": "2022-12-20T19:16:32.4",

"DataRange": null,

"User": {

"Username": "erin.jones@company.com",

"Name": "Erin Jones",

"Email": "erin.jones@company.com"

}

}

],

"ClassificationFullPath": "Global",

"AssetSerialNumber": "",

"CancelledByUser": "",

"Comments": null,

"ModifiedDate": "2022-11-24T18:19:44.94",

"Source": 1,

"Id": "0533012f-2edd-44ab-986d-017fde8e69a9",

"ContentId": "5c8861f3-c6eb-491a-ab8e-090f3b5be9fe",

"ClassificationId": "00000000-0000-0000-0000-000000000000",

"Title": "EVAP123 - Evaporator - Shutdown",

"Version": "2.0.0",

"Status": "Completed",

"CreatedDate": "2022-12-20T19:16:17.387",

"CompletedDate": "2022-12-20T19:16:35.46",

"CancelledDate": "0001-01-01T00:00:00",

"CanCompletionBeCancelled": false,

"WorkOrder": "",

"CompletionNumber": "2022-12-0017",

"SkippedSteps": "",

"TotalNumOfSteps": 7,

"TotalNumOfStepsCompleted": 7,

"AssignedUsers": [

{

"User": {

"Username": "erin.jones@company.com",

"Name": "Erin Jones",

"Email": "erin.jones@company.com",

"Culture": null,

"TwoFactorRequired": false

},

"Role": {

"Id": "eb373287-3689-4431-add8-3e7d63b5332e",

"Name": "Field Operator",

"Description": null,

"IconHref": null,

"Abbreviation": "FO",

"Index": 0,

"Locked": false,

"Selected": false,

"AllowedOperations": null,

"Names": null,

"Abbreviations": null,

"Descriptions": null,

"CultureCode": null

},

"NumOfSteps": 7,

"NumOfStepsCompleted": 7,

"isActive": true

}

],

"HasComments": false,

"HasDataCaptured": true,

"AssetId": "evap123",

"AssetTypeName": "Evaporator",

"ParentCompletion": null,

"CompletionTaskParent": null,

"ForWorkflows": false