Customer Integration Guide#

Customer service allows to manage customer entities. It is possible to create, disable, edit, fetch, list, search through customer entities. It is also possible to fetch some basic information like logo and user roles. In the future even more information will be available in the service.

Customer entities are grouped into customer groups, and each customer must belong to a parent and to a domain. Customer groups are used to facilitate permissions management.

It is important to be aware that several customer entities can belong to a single ‘real world’ client.

The service is used internally.

This documentation will focus on functionalities and structure of V2, which is currently in development. For detailed information about V1 please refer to the Swagger API documentation

Please read the General integration guide to learn the general concepts and common data structures used throughout the Argus API.

Tip

The Swagger API documentation is always up-to-date and lets you try out any query with your user session or an API-key.

In V2 the API has two parts: basic for fetching information and admin which provides access to CRUD operations.

Basic API: Fetching a customer#

Fetching a single customer is done using the customer id or shortname

curl -H "Argus-API-Key: my/api/key" -X GET https://api.mnemonic.no/customers/v2/customer/{idOrShortname}

If successful, the above invocation will return the customer basic model:

{
  "data": {
    "id": 0,
    "name": "string",
    "shortName": "string",
    "domain": {
      "id": 0,
      "name": "string"
    },
    "flags": [
      "disabled"
    ],
    "type": "GROUP"
  }
}

All endpoints for fetching, searching/listing, updating and disabling a customer return the same datamodel.

See the Swagger API documentation for details on the returned data model.

Basic API: Fetching customer user roles#

This endpoint returns a list of customer roles. This endpoint is not yet populated with data.

    curl -H "Argus-API-Key: my/api/key" -X GET "https://api.mnemonic.no/customers/v2/customer/{idOrShortname}
    /userroles"

Basic API: Fetching properties#

This endpoint returns a list of properties limited by limit and offset. The list can be filtered by property keys. The list includes default values from the descriptors.

curl -X 'GET' 
'https://api.mnemonic.no/customers/v2/customer/{idOrShortName}/properties?
domain=domain%20&name=key1&name=key2&includeUnset=false&offset=0&limit=25' 
-H 'accept: application/json' 
-H 'Argus-API-Key: my/api/key'

Basic API: Searching for customers#

Searching for customers can be done using the simple search GET endpoint or the advanced search POST endpoint.

Please read the General integration guide to learn about general concepts for search endpoints.

Basic API: Listing domains#

This endpoint is located in a separate subsection of the API, called domain. It returns a list of domains limited by limit and offset:

curl -H "Argus-API-Key: my/api/key" -X GET "https://api.mnemonic.no/customers/v2/domain?offset=0&limit=25"

Admin API: Fetching a customer#

Fetching a single customer is done using the customer id or shortname, same as in the Basic endpoint.

curl -H "Argus-API-Key: my/api/key" -X GET https://api.mnemonic.no/customeradmin/v2/customer/{idOrShortname}

If successful, the above invocation will return the customer admin model:

{
  "data": [
    {
      "id": 0,
      "name": "string",
      "shortName": "string",
      "domain": {
        "id": 0,
        "name": "string"
      },
      "flags": [
        "disabled"
      ],
      "type": "group",
      "timeZone": {
        "description": "string"
      },
      "createdByUser": {
        "id": 0,
        "shortName": "string",
        "name": "string",
        "domain": {
          "id": 0,
          "name": "string"
        },
        "customer": {
          "id": 0,
          "name": "string",
          "shortName": "string",
          "domain": {
            "id": 0,
            "name": "string"
          }
        }
      },
      "createdTimestamp": 0,
      "lastUpdatedByUser": {
        "id": 0,
        "shortName": "string",
        "name": "string",
        "domain": {
          "id": 0,
          "name": "string"
        },
        "customer": {
          "id": 0,
          "name": "string",
          "shortName": "string",
          "domain": {
            "id": 0,
            "name": "string"
          }
        }
      },
      "lastUpdatedTimestamp": 0,
      "deletedTimestamp": 0,
      "deletedByUser": {
        "id": 0,
        "shortName": "string",
        "name": "string",
        "domain": {
          "id": 0,
          "name": "string"
        },
        "customer": {
          "id": 0,
          "name": "string",
          "shortName": "string",
          "domain": {
            "id": 0,
            "name": "string"
          }
        }
      },
      "language": "norwegian",
      "parent": {
        "id": 0,
        "name": "string",
        "shortName": "string",
        "domain": {
          "id": 0,
          "name": "string"
        }
      }
    }
  ]
}

All endpoints in the Admin API for fetching, searching/listing, updating and disabling a customer return the same Admin Customer datamodel.

See the Swagger API documentation for details on the returned data model.

Admin API: Fetching customer user roles#

This endpoint returns a list of customer roles. This endpoint is not yet populated with data.

    curl -H "Argus-API-Key: my/api/key" -X GET "https://api.mnemonic.no/customeradmin/v2/customer/
    {idOrShortname}/userroles"

Admin API: Searching for customers#

Searching for customers can be done using the simple search GET endpoint or the advanced search POST endpoint.

Please read the General integration guide to learn about general concepts for search endpoints.

Simple search#

For simple search it is possible to search for customers by keywords and filter out the results by parent id or shortname

curl -H "Argus-API-Key: my/api/key"  -X GET "https://api.mnemonic.no/customeradmin/v2/customer?keywords=&parent="

Other parameters include limit, offset and sort.

Advanced search#

Advanced search has access to all possible filtering parameters for customer, and follows the general advanced search structure as described in the General integration guide.

curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/customeradmin/v2/customer/search -d '{
  "customer":["shortname1", "2"],
  "parent":["1","shortname2"],
  "domain":["1", "otherDomain"],
  "includeDeleted":false,
  "includeFlags":[FlagEnumValue1, FlagEnumValue2],
  "excludeFlags":[FlagEnumValue3, FlagEnumValue4],
  "keywords":["keyword1","keyword2"],
  "keywordMatchStrategy":KeywordMatchStrategyEnumValue,
  "keywordFieldStrategy":[KeywordFieldStraregyEnumValue1, KeywordFieldStraregyEnumValue2],
  "subCriteria":[SearchBasicCustomerRequestSubCriteria1, SearchBasicCustomerRequestSubCriteria2],
  "limit":25,
  "offset":0,
  "sortBy":[SortBy1, SortBy2]
}'

See the Swagger API documentation for more details on valid request parameters.

Subcriteria#

Subcriteria are discussed in detail in the General integration guide. We provide some examples related to the Customer API here, but the concepts for subcriteria are described more in detail there.

Using subcriteria allows you to fetch several different dimensions of data in one query, or express which data to exclude. By default, subqueries will be combined with an “OR” logic.

Subqueries with *exclude=true* define a set of criteria for cases to exclude:

curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json"  https://api.mnemonic.no/customeradmin/v2/customer/search -d  '{
  "parent":["mycustomerGroup1"],
  "includeFlags":["excludeFromProduction"],   
  "subCriteria": [
     {"includeFlags":["disabled","customerDataDeleted"],
      "exclude":false}
   ]
}'

Admin API: Listing domains#

This endpoint is located in a separate subsection of the API, called domain. It returns a list of domains limited by limit and offset:

curl -H "Argus-API-Key: my/api/key" -X GET "https://api.mnemonic.no/customeradmin/v2/domain?offset=0&limit=25"

Admin API: Creating new customer#

This endpoint creates new customer in the system, based on a set of parameters. It returns the newly created customer. To create a customer group, please specify type group in the request. To create a non-group customer the type should be leaf.

curl -X 'POST' 
  'https://api.mnemonic.no/customeradmin/v2/customer' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key' 
  -d '{
  "name": "string",
  "shortName": "string",
  "domain": "string",
  "parent": "string",
  "language": "norwegian",
  "timeZone": "string",
  "type": "group",
  "excludeFromProduction": true,
  "networkBaseCustomer": true,
  "singleNetworkDomain": true
}'

Admin API: Updating customer#

This endpoint allows to modify existing customer. It returns the updated customer. It’s possible to change the following:

  • name

  • short name

  • language

  • timezone

  • setting for the following flags:

    • denySubmitForAnonymousUser

    • allowGlobalData

    • excludeFromProduction

    • networkBaseCustomer

    • singleNetworkDomain

    • dataDeleted

curl -X 'PUT' 
  'https://api.mnemonic.no/customeradmin/v2/customer/{idOrShortName}?domain=domain' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "name": "string",
  "shortName": "string",
  "language": "norwegian",
  "timeZone": "string",
  "denySubmitForAnonymousUser": true,
  "allowGlobalData": true,
  "excludeFromProduction": true,
  "networkBaseCustomer": true,
  "singleNetworkDomain": true,
  "dataDeleted": true
}'

Admin API: Disabling customer#

This endpoint allows to disable customer, it should be used after customer data is deleted. The flag Disabled is set on the customer object, but it remains in our db for reference purposes. The disabled customer will no longer show up in searches, unless specifically requested. Only admins that have access privileges for the customer’s parent will be able to view it.

curl -X 'PUT' 
  'https://api.mnemonic.no/customeradmin/v2/customer/{idOrShortName}?domain=domain' 
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

Admin API: Re-enabling customer#

This endpoint allows reenabling a disabled customer.

curl -X 'PUT' 
'https://api.mnemonic.no/customeradmin/v2/customer/{idOrShortName}/reenable?domain=domain' 
-H 'accept: application/json' 
-H 'Argus-API-Key: my/api/key'

Admin API: Pruning customer data#

Use this endpoint to trigger pruning of the customer data in Argus.

Note: This endpoint requires special authorization for the ‘pruneCustomerData’ operation.

curl -X 'DELETE' 
'https://api.mnemonic.no/customers/v2/customer/idOrShortName/data?domain=domain%20&token=authorizationToken' 
-H 'accept: application/json' 
-H 'Argus-API-Key: my/api/key'

Admin API: Moving customer#

This endpoint allows the admins to change the parent of the customer. The new parent has to be of group type, and the move should not grant any additional privileges to new users.

curl -X 'PUT' 
'https://api.mnemonic.no/customeradmin/v2/customer/{idOrShortName}/move?domain=domain' 
-H 'accept: application/json' 
-H 'Content-Type: application/json' 
-H 'Argus-API-Key: my/api/key'
-d '{
"parent": "string"
}'

Admin API: Fetching properties#

This endpoint returns a list of properties limited by limit and offset. The list can be filtered by property keys. The list includes default values from the descriptor.

curl -X 'GET' 
'https://api.mnemonic.no/customeradmin/v2/customer/{idOrShortName}/properties?
domain=domain%20&name=key1&name=key2&includeUnset=false&offset=0&limit=25' 
-H 'accept: application/json' 
-H 'Argus-API-Key: my/api/key'

Admin API: Updating properties#

This endpoint allows updating existing customer properties or adding new ones. Inserted values are validated against the descriptor and accepted only if they are of correct type and have the proper format. It is not possible to update a property that has no descriptor set up.

curl -X 'PUT' 
'https://api.mnemonic.no/customeradmin/v2/customer/{idOrShortName}/properties?domain=domain' 
-H 'accept: application/json' 
-H 'Content-Type: application/json' 
-H 'Argus-API-Key: my/api/key'
-d '{
"properties": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}'

Admin API: Deleting properties#

This endpoint allows the user to reset properties to property descriptor’s default.

curl -X 'DELETE' 
'https://api.mnemonic.no/customeradmin/v2/customer/{idOrShortName}/properties?domain=domain&key=key1&key=key2' 
-H 'accept: application/json' 
-H 'Argus-API-Key: my/api/key'

Admin API: Updating user roles#

To update customer user roles you need to provide which role to update and which user (id or shortname) should be responsible.

curl -X 'PUT' 
'https://api.mnemonic.no/customeradmin/v2/customer/{idOrShortName}/userroles?domain=domain' 
-H 'accept: application/json' 
-H 'Content-Type: application/json' 
-H 'Argus-API-Key: my/api/key'
-d '{
"userRoles": [
{
"role": "technicalAccountManager",
"user": "idOrShortName"
}
]
}'

Admin API - Property Descriptor Management: fetch property descriptor by id or key#

Needed permissions: viewCustomerPropertyDescriptors

This endpoint returns a property descriptor identified by UUID or key. The response can optionally include Json Schema, (settable via query parameter). If include Json Schema query parameter is set to false, JSON Schema field in the response will be null. For basic types JSON Schema is generated and for type jsonType JSON Schema is returned as saved in the db. Special handling is implemented for Property Descriptors of type enumType. Descriptors of type enumType have a predefined set of allowable values that can be managed through specialized endpoints. For more information proceed to section about Admin API - Property Descriptor Enum Type Management: Searching for enum entries.

curl -X 'GET' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{uuidOrKey}?includeSchema=false' 
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

PropertyDescriptorResponse model will be returned.

Note

All endpoints for fetching, searching/listing, creating and updating and disabling a property descriptor return the same data model.

{"id": "c4c32359-2aa0-4448-834d-aa54afa1153b",
    "key": "test2",
    "description": "very good",
    "localizedDescription": "very good",
    "localizedDescriptions": {
      "norwegian": "veldig bra",
      "english": "very good"
    },
    "createdByUser": {
      "type": "user",
      "id": 23,
      "shortName": "someUser",
      "name": "Some User",
      "domain": {
        "id": 1,
        "name": "MNEMONIC"
      },
      "customer": {
        "id": 1,
        "name": "mnemonic",
        "shortName": "mnemonic",
        "domain": {
          "id": 1,
          "name": "MNEMONIC"
        }
      }
    },
    "lastUpdatedByUser": {
      "type": "user",
      "id": 23,
      "shortName": "someUser",
      "name": "Some User",
      "domain": {
        "id": 1,
        "name": "MNEMONIC"
      },
      "customer": {
        "id": 1,
        "name": "mnemonic",
        "shortName": "mnemonic",
        "domain": {
          "id": 1,
          "name": "MNEMONIC"
        }
      }
    },
    "deletedByUser": null,
    "createdTimestamp": 1678206365456,
    "lastUpdatedTimestamp": 1678206365456,
    "deletedTimestamp": 0,
    "flags": [],
    "defaultValue": "string",
    "section": "notification",
    "type": "string",
    "jsonSchema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "string"
    }
  }

Admin API - Property Descriptor Management: update property descriptor#

Needed permissions: updateCustomerPropertyDescriptor

This endpoint allows the user to update a property descriptor identified by UUID or key by using data from the request. It is possible to update:

  • localizedDescriptions - english description is required and can not be deleted or updated to “”

  • section

  • defaultValue - has to be valid according to type (for the validation rules for jsonType read on JSON Schema validation)

  • type - if update to jsonType JSON Schema must be provided in addition. If a descriptor is updated to enumType an enum entry is automatically generated for the default value of the descriptor.

  • schema - possible to update only for type jsonType,

    Note

    It is not possible to update both default value and JSON Schema at the same time, when updating the schema it is verified if the default value is still valid according to the schema and when the default value is updated it is
    always validated against the schema for the jsonType

  • deprecated - flag the descriptor as deprecated (has to be done before the descriptor is deleted)

curl -X 'PUT' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{uuidOrKey}' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "localizedDescriptions": {
    "english": "string",
    "norwegian": "string"
  },
  "section": "notification",
  "defaultValue": "string",
  "type": "string",
  "schema": "JsonNode",
  "deprecated": false
}'

Admin API - Property Descriptor Management: delete property descriptor#

Needed permissions: deleteCustomerPropertyDescriptor

This endpoint allows the user to delete a previously deprecated property descriptor identified by UUID or key. Please note that some customers may still have values for the descriptor, check the log message for information.

curl -X 'DELETE' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{uuidOrKey}' 
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

Admin API - Property Descriptor Management: fetch JSON Schema for a property descriptor by id or key#

Needed permissions: viewCustomerPropertyDescriptors

This endpoint returns a JsonNode with JSON Schema for a property descriptor identified by UUID or key. For basic types schema is generated and for jsonType the schema saved in db is returned.

curl -X 'GET' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{uuidOrKey}/jsonschema' 
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

Admin API - Property Descriptor Management: Searching for descriptors#

Needed permissions: viewCustomerPropertyDescriptors

Searching for descriptors can be done using the simple search GET endpoint or the advanced search POST endpoint.

Please read the General integration guide to learn about general concepts for search endpoints.

Simple search#

For simple search it is possible to search for descriptors by keywords and sort the results

curl -X 'GET'  
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor?offset=0&limit=25'
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

Other parameters include limit and offset.

Advanced search#

Advanced search has access to all possible filtering parameters for property descriptors, and follows the general advanced search structure as described in the General integration guide.

curl -X 'POST'   
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/search' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "section": [
    "notification"
  ],
  "type": [
    "string"
  ],
  "includeFlags": [
    "deleted"
  ],
  "excludeFlags": [
    "deprecated"
  ],
  "keywords": [
    "string"
  ],
  "subCriteria": [
    {
      "section": [
        "notification"
      ],
      "type": [
        "string"
      ],
      "includeFlags": [
        "deprecated"
      ],
      "excludeFlags": [
        "deprecated"
      ],
      "keywords": [
        "string"
      ],
      "subCriteria": [
        "string"
      ],
      "required": false,
      "exclude": false
    }
  ],
  "includeDeleted": false,
  "limit": 0,
  "offset": 0,
  "sortBy": [
    "key"
  ]
}'

Note

Search options “keywordMatchStrategy” and “keywordFieldStrategy” are not supported. See the Swagger API documentation for more details on valid request parameters.

Admin API - Property Descriptor Management: add a new property descriptor#

Needed permissions: createCustomerPropertyDescriptors

This endpoint creates a descriptor based on parameters provided

  curl -X 'POST' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "key": "test2",
  "localizedDescriptions": {
    "norwegian": "veldig bra",
    "english": "very good"
  },
  "section": "notification",
  "defaultValue": "string",
  "type": "string",
  "schema": ""
}'

Note

The default value will be validated against the type provided and for jsonType it will be validated against JSON Schema.

Note

Description in english is required.

Note

If a descriptor of enumType is created an enum entry is automatically generated for the default value of the descriptor.

Admin API - Property Descriptor Enum Type Management: Searching for enum entries#

Needed permissions: viewCustomerPropertyDescriptors

Searching for enum entries can be done using the simple search GET endpoint or the advanced search POST endpoint.

Please read the General integration guide to learn about general concepts for search endpoints.

Simple search#

For simple search it is possible to search for enum entries for a descriptor by keywords and sort the results

curl -X 'GET' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{enumTypeDescritporUUIDOrKey}/values?
  offset=0&limit=25&keywords=keyword1&sortBy=value' 
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

Other parameters include limit and offset.

Advanced search#

Advanced search has access to all possible filtering parameters for enum entries of a property descriptor, and follows the general advanced search structure as described in the General integration guide.

curl -X 'POST'   
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{enumTypeDescriptorUUIDOrKey}/search' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "keywords": [
    "string"
  ],
  "subCriteria": [
    {
      "keywords": [
        "string"
      ],
      "subCriteria": [
        "string"
      ],
      "keywordMatchStrategy": "any",
      "keywordFieldStrategy": [
        "value"
      ],
      "required": false,
      "exclude": false
    }
  ],
  "keywordMatchStrategy": "any",
  "keywordFieldStrategy": [
    "value"
  ],
  "limit": 0,
  "offset": 0,
  "sortBy": [
    "value"
  ]
}'

See the Swagger API documentation for more details on valid request parameters.

The search endpoints return a list of enum entries. CustomerPropertyDescriptorEnumEntryResponse model will be returned.

Note

All endpoints related to enum entries management return the same data model.

{
  "propertyDescriptorId": "021f9aaa-26c8-40f5-b6b9-6493e7d85e8f",
  "value": "value1",
  "localizedValue": "value1",
  "localizedValues": {
    "english": "value1",
    "norwegian": "value1"
  },
  "description": "Some value",
  "localizedDescription": "Some value",
  "localizedDescriptions": {
    "english": "Some value",
    "norwegian": "Some value"
  }
}

Admin API - Property Descriptor Enum Type Management: add a new enum entry#

Needed permissions: updateCustomerPropertyDescriptors

This endpoint creates an enum entry for a descriptor based on parameters provided

  curl -X 'POST' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{enumTypeDescritporUUIDOrKey}/values' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "value": "string",
  "localizedValues": {
    "english": "string",
    "norwegian": "string"
  },
  "localizedDescriptions": {
    "english": "string",
    "norwegian": "string"
  }
}'

Note

Enum entries can be created only for descriptors of type enumType.

Note

The value is required and it is not editable. To edit the displayed value it is possible to do, by editing localizedValues.

Note

Description and localized value in english is required.

Admin API - Property Descriptor Enum Type Management: update property descriptor enum entry#

Needed permissions: updateCustomerPropertyDescriptor

This endpoint allows the user to update an enum entry for a property descriptor identified by UUID or key by using data from the request. It is possible to update:

  • localizedDescriptions - english description is required and can not be deleted or updated to “”

  • localizedValues - english value is required and can not be deleted or updated to “”

curl -X 'PUT' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{enumTypeDescritporUUIDOrKey}/values/
  {enumEntryUUIDOrValue}' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "localizedDescriptions": {
    "english": "string",
    "norwegian": "string"
  },
  "localizedValues": {
    "english": "string",
    "norwegian": "string"
  }
}'

Admin API - Property Descriptor Enum Type Management: delete property descriptor enum entry#

Needed permissions: updateCustomerPropertyDescriptor

This endpoint allows the user to delete an enum entry, identified by UUID or value, from a property descriptor identified by UUID or key.

curl -X 'DELETE' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{enumTypeDescritporUUIDOrKey}/values/
  {enumEntryUUIDOrValue}' 
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

Danger

The enum entry is deleted permanently and can’t be restored.