REST Examples

The following are some examples of different interactions with the REST service using Powershell commands.

Note

It is suggested that interactions with the REST API are thoroughly tested prior to use in a Production environment. Modifying data directly via the REST APIs can have a destructive effect on a NEXUS database if not tested properly.

Authenticating

The following provides an example of how to authenticate against the REST API using powershell. This is required before any other interaction with the REST API.

$baseUri = "https://{icWebUrl}/data/icweb.dll/"
$loginUri = $baseUri + "security/login"

# API Key from the user account in NEXUS. We need to base64 encode it for the authentication request.
$apiKey = {apiKey}

$apiKeyBytes = [System.Text.Encoding]::UTF8.GetBytes($apiKey)
$apiKeyEncoded = [System.Convert]::ToBase64String($apiKeyBytes)

# Build "Authorization" header for login request.
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Authorization", "apikey " + $apiKeyEncoded)

# Login to the REST API, result is JSON containing the authentication hash.
$hash = Invoke-RestMethod -method GET -uri $loginUri -Headers $headers

Request a list of Rows

Following on from the above authentication, we now have a valid hash to be able to query other items from the REST API. The below requests all rows from the Workpack business object.

# Base BO REST API
$boUri = $baseUri + "bo/"

# Build the URI to request all the rows from the Workpack business object.
$uri = $boUri + "Workpack/" + "?hash=" + $hash.hash
$workpackJson = Invoke-RestMethod -method GET -uri $uri

# Output the list of Workpacks
$workpackJson.rows | Format-Table -Property Workpack_ID, Name

Note

If there are more than 100 rows in the workpack table you will need to make subsequent requests to retrieve the rest of the rows.

Request a list of rows with a filter

If you wanted to only return a list of workpacks where the Revision is set to “Planning” we would do that using a filter.

# Create filter object
$filter = @{
        where =
        @(
                @{
                        field = "Revision_ID.Name"
                        value = "Planning"
                }
        )
}

# Convert filter object to Json.
$filterJson = $filter | ConvertTo-Json

# Add the filter as a X-NEXUS-Filter http header.
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("X-NEXUS-Filter", $filterJson)

# Build the REST uri for the Workpack business object and Invoke the REST method.
$uri = $boUri + "Workpack/?hash=" + $hash.hash
$workpacks = Invoke-RestMethod -method GET -uri $uri -Headers $headers

# Output the list of workpacks
$workpacks.rows | Format-Table

Generate a Report Template

The following generates a report template and emails it to a specified person.

# Base report REST URI
$reportUri = $baseUri + "web/generateReport"

# Set the recipient for the report email/
$recipient = "joe.bloggs@nexusic.com"

# Set the report format to RTF - You can use HTML and XLSX as well.
$format = "RTF"

# Set the report template key to 16, this specifies the report template to generate.
$reportTemplate = "16"

# Generate Report Template with ID of 16, using RTF format and email it to a specific person.
$uri = $reportUri + "?key=" + $reportTemplate + "&format=" + $format + "&recipient=" + $recipient + "&hash=" + $hash.hash
Invoke-RestMethod -method POST -uri $uri

Insert a New Row

The following creates a new Workpack, setting the initial values of that Workpack.

# Build an object that contains the specified values for Name, Actual_Start, Description and ReadOnly
$workpackRow = @{
        Name = "2015 ROV Inspection"
Actual_Start = "2015-05-15T00:00:00.000Z"
Description = "Annual 2015 full field rov inspection"
ReadOnly = $false
}
$body = $workpackRow | ConvertTo-Json

# Build the URI to request all the rows from the Workpack business object.
$uri = $boUri + "Workpack/0?hash=" + $hash.hash
$newRow = Invoke-RestMethod -method PUT -body $body -uri $uri

# Output the the new Workpack row
$newRow.rows | Format-Table -Property Workpack_ID, Name

Updating an existing Row

Following on from the insert, we can use the row in $newRow.Rows to then update the name of the workpack and abbreviation.

# Update Workpack Abbreviation and Name
$workpackRow = @{
        Abbreviation = "2015_ROV"
        Name = "2015 - Annual ROV Inspection"
}
$body = $workpackRow | ConvertTo-Json

# Build the URI - must include the Workpack_ID from the new row so the REST api knows what row we are updating.
$uri = $boURI + "Workpack/" + $newRow.rows[0].Workpack_ID + "?hash=" + $hash.hash
$updatedRow = Invoke-RestMethod -method POST -body $body -uri $uri

$updatedRow.rows

Getting information on a Function

$functionName = "Compare A = B"
$functionUri = $baseUri + "function/"

# Build the URI - must include the Workpack_ID from the new row so the REST api knows what row we are updating.
$uri = $functionURI + "/" + $functionName + "?hash=" + $hash.hash
$function = Invoke-RestMethod -method GET -uri $uri

$function