Inbound API Assets - TechnicheGroup/urgent-rest GitHub Wiki

Create Assets

POST /assets/{tenant}

The following details the properties available when creating an asset. Note that many of them are optional. Due to the Asset Tag Number being optional, the response returns a GUID which is used to identify the asset in other parts of the API, such as Scheduled Tasks Inspections and Reactive Tasks.

Path	Notes
ParentAssetIdentifier	(Optional) The Asset Identifier GUID of the Parent Asset you want to assign this Asset as a child to. Leave as blank for Parent asset. (V41)
SiteCode	The Site Code to attached the asset to. See Sites for more info.
MatrixCode	The asset matrix code used to categorize the asset. See Matrix By Type on how to get this code.
Manufacturer	The asset manufacturer. Must already exist in the system. See the Manufacturer and Manufacturer/Model mapping methods for more info
Model	The asset model. Must already exist in the system. See Model and Manufacturer/Model mapping methods for more info.
SerialNumber	The asset's serial number. Optional
AssetTag	The asset's tag number. This may or may not be required and may or may not be generated automatically for you based on the Tenant configuration.
Description	Free text description
Quantity	Quantity. Integer, optional.
InstallationDate	The asset's installation date. The time component is ignore. Optional
PurchaseDate	The asset's purchase date. The time component is ignored. Optional
PurchaseValue	The value of the asset upon purchase. Optional.
CurrentValue	The current value of the asset. Optional
YearOfManufacture	The year the asset was manufactured. Integer, optional
LifeSpan	The lifespan of the asset. Optional
LifeSpan.Value	The number representing the asset's life span. Integer, optional. E.g. if the lifespan is 20 years then this should be "20"
LifeSpan.Unit	The unit representing the asset's lifespan. Should be one of Days, Months or Years.
Category	The asset's category. One of the Asset Category reference list options. See References for more info. Optional
Owner	The asset's owner. One of the Asset Owner reference list options. See References for more info. Optional
Location	The asset's location. One of the Asset Location reference list options. See References for more info. Optional
LocationDetail	Free text detail on the asset's location
Status	The asset's status. One of the Asset Status reference list options. See References for more info. Optional
MaintenanceProvider	The asset's maintenance provider. One of the Asset Maintenance Provider reference list options. See References for more info. Optional
ServiceCompany	The asset's Service Company. Must already exist in the system. Optional
SellerCompany	The asset's seller company. Must already exist in the system. Optional
Warranty	Information about the asset's warranty.
Warranty.Company	The provider of the repairs when under warranty. Must already exist in the system. If the asset is under warranty and the company is associated with a maintenance supplier then the task will be dispatched them them instead of the normally-assigned maintenance supplier.
Warranty.CommercialOwner	The company that commercially owns the warranty. Must already exist in the system. Optional
Warranty.PeriodValue	The period of the warranty. Optional Integer. If the warranty lasts for three years then this value should be "3"
Warranty.PeriodUnit	The unit representing the asset's warranty. One of Day, Month or Year
Condition	The current operational condition of the asset. One of the Asset Condition reference list options. See References for more info.
ConditionComment	Free text description of the asset's current conidition
Visual Condition	The current visual condition of the asset. One of the Asset Condition reference list options. See References for more info.
CustomFields[]	Custom Fields for the asset. Listing is determined by the output of the Custom Field methods
CustomFields[].Name	The name of the custom field.
CustomFields[].Text	Ignored when creating or updating an asset
CustomFields[].Answer	The value of the custom field.
CustomFields[].Type	Ignored when creating or updating an asset
CustomFields[].Question	Ignored when creating or updating an asset

Requests

Minimum Request

The following details the minimum information required to create an asset in the Urgent Platform

{
  "SiteCode": "R732",
  "MatrixCode": "04-04-01-A0",
  "Manufacturer": "ACME Inc",
  "Model": "AC001/X"
}

Response Examples

Success Example

Indicates that the asset was successfully created.

{
    "AssetIdentifier": "4FB66F26-FA33-4E32-A551-4666D51F31A0",
    "Messages": null
}

Failure Example

Indicates that the asset was not created.

{
    "AssetIdentifier": null,
    "Messages": [
        {
            "Key": "BrokenRule_Site_NotFound",
            "Value": "The specified site was not found"
        },
        {
            "Key": "BrokenRule_Matrix_Find_NotFound",
            "Value": "No matrix found with this code"
        }
    ]
}

Update Assets

PUT /assets/{tenant}/{assetIdentifier}

The body of the Update Assets method uses the same body as the Create Asset method, however the assetIdentifier variable should be replaced with the Asset Identifier (returned on successful creation of an asset or via the Read Assets response) of the asset you are updating. When updating an Asset all fields are required in the body of the request.

Response Examples

Success Example

Indicates that the asset was successfully updated.

{
    "Messages": null
}

Failure Example

Indicates that the asset was not updated.

{
    "Messages": [
        {
            "Key": "BrokenRule_Site_NotFound",
            "Value": "The specified site was not found"
        },
        {
            "Key": "BrokenRule_Matrix_Find_NotFound",
            "Value": "No matrix found with this code"
        }
    ]
}

Move Assets

PUT /assets/{tenant}/{assetIdentifier}/move

To move an asset between sites the assetIdentifier variable should be replaced with the Asset Identifier value of the asset you want to move and the body of the request should contain the Site Code of the Site you are moving the asset to and an optional note.

Example Request

{
    "SiteCode": "99999",
    "Note": "Moving to correct site"
}

Response Examples

Success Example

Indicates that the asset was successfully moved.

{
    "Messages": null
}

Failure Example

Indicates that the asset was not moved.

{
    "Messages": [
        {
            "Key": "BrokenRule_Site_NotFound",
            "Value": "The specified site was not found"
        }
    ]
}

Write Off Assets

PUT /assets/{tenant}/{assetIdentifier}/writeoff

To write off an asset the assetIdentifier variable should be replaced with the Asset Identifier value of the asset you want to move and the body of the request should contain an optional note on why the asset is being written off.

Example Request

{
    "Note": "Asset is no longer in use"
}

Response Examples

Success Example

Indicates that the asset was successfully written off.

{
    "Messages": null
}

Failure Example

Indicates that the asset was not written off.

{
    "Messages": [
        {
            "Key": "BrokenRule_Asset_AssetNotFound",
            "Value": "The specified asset was not found"
        }
    ]
}

Read Assets

GET /assets/{tenant}/{site}/{matrixCode}

Assets are retrieved on a Site and Matrix Code basis with the Matrix Code allowing for partial searches. Details on each of the properties that can be returned when reading assets via the REST API for the site and matrix item.

Path	Notes
AssetIdentifier	GUID representing the asset
ParentAssetIdentifier	GUID representing the parent asset
SiteCode	Identifier of the asset's site
MatrixCode	The code of the asset's matrix item, unique to the tenant
Manufacturer	Name of the asset's manufacturer
Model	Model of the asset
SerialNumber	Asset's serial number
AssetTag	Asset's TAG number
Description	Asset's description
Quantity	Quantity of the asset
InstallationDate	When the asset was installed
PurchaseDate	When the asset was purchased
PurchaseValue	Purchase value of the asset
YearOfManufacture	Year of manufacturer of the asset
Lifespan	life span of the asset in terms of unit and value, e.g. 2 years
Category	Category of the asset
Owner	Owner of the asset
Location	Asset's location
LocationDetail	Detail of the asset's location
Status	Status of the asset
MaintenanceProvider	Maintenance provider of the asset
ServiceCompany	Asset's service company
SellerCompany	Asset's seller company
Warranty	Warranty of the asset including the company and the period (e.g. 2 years)
Condition	Operational Condition of the asset
VisualCondition	Visual Condition of the asset
ConditionComments	Condition comments of the asset
AssetDowntimeInHours	The total number of Hours the Asset has been flagged as being down (Unavailable to make sales) for its current lifespan. Combined with AssetDowntimeInMinutes to give an overall hh:mm total
AssetDowntimeInMinutes	The total number of Minutes the Asset has been flagged as being down (Unavailable to make sales) for its current lifespan. Combined with AssetDowntimeInHours to give an overall hh:mm total
CustomFields[].Name	Name of the custom field
CustomFields[].Text	Text of the custom field
CustomFields[].Answer	Answer of the custom field
CustomFields[].Type	Type of the custom field
CustomFields[].Parent	Parent of the custom field
Document[].AggregateId	GUID representing the document
Document[].FileName	Filename of the document
Document[].MimeType	Mime type of the document
Document[].FolderPath	Folder path of the document
Document[].FileSize	File size of the document
Document[].DocumentCategories	Document categories of the document

Read Asset Models

GET /assets/assetmodels/{tenant}/{matrixCode}

The Asset Model method returns a list of available Models for the given Asset Matrix Code. This code when searching can be a partial code to retrieve all Models for a larger range.

Example Response

{
    "Models": [
        {
            "Model": "HP ENVY 6430e",
            "Code": "6430e",
            "AssetMatrixCodes": [
                "01-01-01"
            ],
            "IsActive": true,
            "Manufacturers": [
                "Hewlett Packard"
            ]
        },
        {
            "Model": "PIXMA G1530",
            "Code": "PIXMAG1530",
            "AssetMatrixCodes": [
                "01-01-01"
            ],
            "IsActive": true,
            "Manufacturers": [
                "Canon"
            ]
        }
    ]
}

Read Asset Manufacturers

GET /assets/assetmanufacturers/{tenant}

The Asset Manufacturers method returns a list of available Manufacturers for the given tenant.

Example Response

{
    "Manufacturers": [
        "Canon",
	"Hewlett Packard"
    ]
}

Read Asset Manufacturer and Model mappings

GET /assets/assetmanufacturerswithmodels/{tenant}

In Urgent the Manufacturers and Models are linked together so that you can only assign certain Models if you select the correct Manufacturer first. To get a list of these linking records use this method in conjunction with the Model and Manufacturer methods to determine which correct Model and Manufacturer you need to create or update an Asset.

Example Response

{
    "Manufacturers": [
        {
            "Manufacturer": " Hewlett Packard",
            "Models": [
                {
                    "Model": "HP ENVY 6430e",
                    "Code": "6430e",
                    "AssetMatrixCodes": [
                      "01-01-01"
                    ]
                }
            ]
        },
        {
            "Manufacturer": "Canon",
            "Models": [
                {
                    "Model": "PIXMA G1530",
                    "Code": "PIXMAG1530",
                    "AssetMatrixCodes": [
                       "01-01-01"
                    ]
                }
            ]
        }
    ]
}

Create Asset Model

POST /assets/assetmodels/{tenant}

This method allows for the creation of an asset model as well as it's manufacturer mappings and matrix mappings. MatrixCodes and Manufacturers are both required fields, if either are left empty an error message will be returned.

Example Request

{
  "Name": "1.8m Wall Chiller",
  "MatrixCodes": [
    "04-04-01-A0",
    "04-04-01-A1"
  ],
  "Manufacturers": [
    "ACME Inc",
    "FridgeCo"
  ],
  "Code": "WC-001"
}

Response Examples

Success Example

Indicates that the asset model was successfully created.

{
    "Messages": null
}

Failure Example

Indicates that the asset model was not created.

{
    "Messages": [
        {
            "Key": "BrokenRule_Asset_Model_RestAPI_InvalidMatrixCodes",
            "Value": "One or more provided matrix codes are invalid"
        },
        {
            "Key": "BrokenRule_Asset_Model_RestAPI_InvalidManufacturers",
            "Value": "One or more provided manufacturers are invalid"
        }
    ]
}