# ================================================================================ # Copyright (c) 2019-2020 AT&T Intellectual Property. All rights reserved. # Modifications Copyright (C) 2019 Nordix Foundation. # ================================================================================ # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limits under the License. # ============LICENSE_END========================================================= --- openapi: '3.0.3' info: version: "0.0.0" title: "License Usage Manager (LUM) API" description: RESTfull-ish API for License Usage Manager - json based license: name: "Apache 2.0" url: "http://www.apache.org/licenses/LICENSE-2.0.html" contact: name: Acumos License Management url: https://wiki.acumos.org/display/LM/ externalDocs: description: LUM docs url: https://docs.acumos.org/en/latest/submodules/license-usage-manager/docs/index.html servers: - url: / description: root - url: /lum description: reverse proxy access tags: - name: "swid-tag" description: "CRUD on swidTag - software-identity tag with licenseProfile attached to it" - name: "asset-usage-agreement" description: "CRUD on assetUsageAgreement that is the collection of permissions/rights-to-use" - name: "asset-usage-agreement-restriction" description: "CRUD on assetUsageAgreementRestriction with all the subscriber company restrictions against the asset-usage agreement" - name: "asset-usage" description: "request the entitlement on the asset usage or record an event" - name: "asset-usage-tracking" description: "reports of all requests with decisions per supplier" - name: "info" description: "LUM healthcheck and info" - name: "admin" description: "LUM admin to see and change the settings" paths: # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # /api/healthcheck: get: tags: ["info"] description: returns healthcheck information operationId: getHealthcheck responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/HealthcheckResponse' /: get: tags: ["info"] description: returns healthcheck information operationId: getInfo responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/HealthcheckResponse' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # /admin/config: get: tags: ["admin"] description: returns current configuration of LUM server operationId: getAdminConfig responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/AdminConfigResponse' put: tags: ["admin"] description: update the current configuration of LUM server operationId: putAdminConfig requestBody: description: request to update the current configuration of LUM server required: true content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/AdminConfigRequest' responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/AdminConfigResponse' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # /admin/recent-errors: get: tags: ["admin"] description: returns the last 20 exceptions on LUM server operationId: getRecentErrors responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/BaseRequestTop' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # /api/v1/swid-tag: parameters: - name: swTagId example: ee48b699-3b16-4391-884c-1bec557f32b9 required: true in: query description: globally unique identifier of the software tag up to its version (in Acumos it is revisionId) schema: type: string get: tags: ["swid-tag"] operationId: getSwidTag description: returns swidTag record for swTagId responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/GetSwidTagResponse' 204: description: swidTag not found headers: requestId: description: request id schema: type: string format: uuid requested: description: timestamp of the request schema: type: string format: date-time swTagId: description: echo back swTagId example: "0bde3cf2-7a91-40ff-af5f-2d314e677e6a" schema: type: string status: description: saying that the record not found schema: type: string default: "swidTag not found" 224: description: swidTag revoked content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/RevokeSwidTagResponse' put: tags: ["swid-tag"] description: updates swidTag record for swTagId operationId: putSwidTag requestBody: description: request to update swidTag record for swTagId required: true content: 'application/json; charset=utf-8': example: userId: admin swidTag: swTagId: "ee48b699-3b16-4391-884c-1bec557f32b9" swPersistentId: 0d70ca44-2868-2042-8028-6b9a5e7c8eec swVersion: '1' licenseProfileId: 08731dff-2a30-44b7-b46c-aec1c2d0a4d7 softwareLicensorId: Company A swCategory: CL swCatalogs: - swCatalogId: b934935e-caad-11e9-9a2f-2edc1426c78a swCatalogType: RS swProductName: example-model swCreators: - modelowner1 licenseProfile: licenseProfileId: 08731dff-2a30-44b7-b46c-aec1c2d0a4d7 isRtuRequired: true schema: $ref: '#/components/schemas/PutSwidTagRequest' responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/PutSwidTagResponse' delete: tags: ["swid-tag"] description: revoke the swidTag for swTagId operationId: revokeSwidTag parameters: - name: userId required: true example: admin in: query description: identifier of the user schema: type: string responses: 204: description: swidTag not found headers: requestId: description: request id schema: type: string format: uuid requested: description: timestamp of the request schema: type: string format: date-time swTagId: description: echo back swTagId schema: type: string status: description: saying that the record not found schema: type: string default: "swidTag not found" 224: description: swidTag revoked content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/RevokeSwidTagResponse' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # /api/v1/swid-tag-creators: parameters: - name: swTagId required: true example: ee48b699-3b16-4391-884c-1bec557f32b9 in: query description: globally unique identifier of the software tag up to its version (in Acumos it is revisionId) schema: type: string put: tags: ["swid-tag"] operationId: setSwidTagCreators description: updates the creators on the swidTag record for swTagId requestBody: description: request to update creators on the swidTag record for swTagId required: true content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/SetSwidTagCreatorsRequest' responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/SetSwidTagCreatorsResponse' 204: description: swidTag not found headers: requestId: description: request id schema: type: string format: uuid requested: description: timestamp of the request schema: type: string format: date-time swTagId: description: echo back swTagId schema: type: string status: description: saying that the record not found schema: type: string default: "swidTag not found" # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # /api/v1/swid-tags: get: tags: ["swid-tag"] operationId: getActiveSwidTags description: returns the collection of active swidTag records responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/GetActiveSwidTagsResponse' /api/v1/swid-tags/available-entitlement: get: tags: ["swid-tag"] operationId: getSwidTagsWithAvailableEntitlement description: returns the collection of swidTag records with available-entitlement for the userId to perform the requested action at this moment parameters: - name: userId required: true example: acu-composer in: query description: identifier of the user per action schema: type: string - name: action required: true example: aggregate in: query description: identifier of the action on swidTags with available-entitlement schema: type: string responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/GetEntitledSwidTagsResponse' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # /api/v1/asset-usage-agreement: parameters: - name: softwareLicensorId required: true example: Company A in: query description: identifier of the entity that issued the licenseProfile schema: type: string - name: assetUsageAgreementId example: "acumos://software-licensor/Company A/agreement/3eb8c43a-bf19-46ab-8392-99c7efdf4106" required: true in: query description: UID key to assetUsageAgreement in IRI or URI format schema: type: string get: tags: ["asset-usage-agreement"] operationId: getAssetUsageAgreement description: returns assetUsageAgreement record with all the rights to use for assetUsageAgreementId responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/GetAssetUsageAgreementResponse' 204: description: assetUsageAgreement not found headers: requestId: description: request id schema: type: string format: uuid requested: description: timestamp of the request schema: type: string format: date-time softwareLicensorId: description: identifier of the entity that issued the licenseProfile schema: type: string example: Company A assetUsageAgreementId: description: echo back UID key to assetUsageAgreement in IRI or URI format schema: type: string status: description: saying that the record not found schema: type: string default: "assetUsageAgreement not found" 224: description: assetUsageAgreement revoked content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/RevokeAgreementResponse' put: tags: ["asset-usage-agreement"] description: updates assetUsageAgreement record for assetUsageAgreementId operationId: putAssetUsageAgreement requestBody: description: request to update assetUsageAgreement record for assetUsageAgreementId required: true content: 'application/json; charset=utf-8': example: userId: admin requestId: "3fa85f64-5717-4562-b3fc-2c963f66afa6" requested: "2020-02-06T19:03:12.240Z" assetUsageAgreement: softwareLicensorId: Company A assetUsageAgreementId: "acumos://software-licensor/Company A/agreement/3eb8c43a-bf19-46ab-8392-99c7efdf4106" agreement: "@context": "@vocab": https://www.w3.org/ns/odrl.jsonld# vcard: http://www.w3.org/2006/vcard/ns# "@type": Agreement uid: "acumos://software-licensor/Company A/agreement/3eb8c43a-bf19-46ab-8392-99c7efdf4106" assignee: "@type": - Party - vcard:Organization vcard:hasUrl: companyb.com vcard:fn: Company B vcard:hasEmail: team@companyb.com refinement: - rightOperand: "@value": '10' "@type": xsd:integer "@type": Constraint leftOperand: lum:countUniqueUsers operator: lteq assigner: "@type": - Party - vcard:Organization vcard:hasUrl: companya.com vcard:fn: Company A vcard:hasEmail: sales@companya.com target: refinement: - "@type": Constraint leftOperand: lum:swProductName operator: lum:in rightOperand: - face-detect "@type": Target permission: - uid: "acumos://software-licensor/Company A/permission/98378924-84ff-41f5-87ac-02fd2012c727" "@type": Rule action: - acumos:deploy - acumos:download - modelrunner:predict - modelrunner:train constraint: - rightOperand: "@value": '100' "@type": xsd:integer "@type": Constraint leftOperand: count operator: lt prohibition: - "@type": Rule action: - transfer - aggregate uid: "acumos://software-licensor/Company A/prohibition/85f6ab36-3ede-461a-ad57-23b941264d10" schema: $ref: '#/components/schemas/PutAssetUsageAgreementRequest' responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/PutAssetUsageAgreementResponse' 400: description: invalid input data content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/ErrorResponse' delete: tags: ["asset-usage-agreement"] description: revoke the assetUsageAgreement for assetUsageAgreementId operationId: revokeAssetUsageAgreement parameters: - name: userId required: true example: admin in: query description: identifier of the user schema: type: string responses: 204: description: assetUsageAgreement not found headers: requestId: description: request id schema: type: string format: uuid requested: description: timestamp of the request schema: type: string format: date-time softwareLicensorId: description: identifier of the entity that issued the licenseProfile schema: type: string example: Company A assetUsageAgreementId: description: echo back UID key to assetUsageAgreement in IRI or URI format schema: type: string status: description: saying that the record not found schema: type: string default: "assetUsageAgreement not found" 224: description: assetUsageAgreement revoked content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/RevokeAgreementResponse' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # /api/v1/asset-usage-agreement-restriction: parameters: - name: softwareLicensorId required: true example: Company A in: query description: identifier of the entity that issued the licenseProfile schema: type: string - name: assetUsageAgreementId required: true example: "acumos://software-licensor/Company A/agreement/3eb8c43a-bf19-46ab-8392-99c7efdf4106" in: query description: UID key to assetUsageAgreement in IRI or URI format. possible format "http://software-licensor//agreement/" schema: type: string put: tags: ["asset-usage-agreement-restriction"] description: updates assetUsageAgreement record for assetUsageAgreementId with the subscriber company restrictions operationId: putAssetUsageAgreementRestriction requestBody: description: request to update assetUsageAgreement record for assetUsageAgreementId with the subscriber company restrictions required: true content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/PutAssetUsageAgreementRestrictionRequest' responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/PutAssetUsageAgreementResponse' 204: description: assetUsageAgreement not found headers: requestId: description: request id schema: type: string format: uuid requested: description: timestamp of the request schema: type: string format: date-time softwareLicensorId: description: identifier of the entity that issued the licenseProfile schema: type: string example: Company A assetUsageAgreementId: description: echo back UID key to assetUsageAgreement in IRI or URI format example: "acumos://software-licensor/Company A/agreement/3eb8c43a-bf19-46ab-8392-99c7efdf4106" schema: type: string status: description: saying that the record not found schema: type: string default: "assetUsageAgreement not found" 224: description: assetUsageAgreement revoked content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/RevokeAgreementResponse' 400: description: invalid input data content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/ErrorResponse' delete: tags: ["asset-usage-agreement-restriction"] description: revoke the subscriber company restriction on assetUsageAgreement for assetUsageAgreementId operationId: revokeAssetUsageAgreementRestriction parameters: - name: userId required: true example: admin in: query description: identifier of the user schema: type: string responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/PutAssetUsageAgreementResponse' 204: description: assetUsageAgreement not found headers: requestId: description: request id schema: type: string format: uuid requested: description: timestamp of the request schema: type: string format: date-time softwareLicensorId: description: identifier of the entity that issued the licenseProfile schema: type: string example: Company A assetUsageAgreementId: description: echo back UID key to assetUsageAgreement in IRI or URI format example: "acumos://software-licensor/Company A/agreement/3eb8c43a-bf19-46ab-8392-99c7efdf4106" schema: type: string status: description: saying that the record not found schema: type: string default: "assetUsageAgreement not found" 224: description: assetUsageAgreement revoked content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/RevokeAgreementResponse' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # /api/v1/asset-usage: parameters: - name: assetUsageId required: true example: 38935f5c-293b-4e00-91ad-14d5de66eee3 in: query description: UID key to assetUsage in IRI or URI format schema: type: string put: tags: ["asset-usage"] description: | request for entitlement of the action on new asset (no assetUsageId) or previously assigned asset with assetUsageId operationId: requestAssetUsage requestBody: description: request for entitlement of the action on the asset required: true content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/PutAssetUsageRequest' responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/PutAssetUsageSuccessResponse' 402: description: denied assetUsage. At least one assetUsage has usageEntitled = false. - If usageEntitled = false, assetUsageDenial is provided for that assetUsage - If usageEntitled = true and isRtuRequired = true, entitlement is provided for that assetUsage content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/AssetUsageResponse' get: tags: ["asset-usage"] description: returns assetUsage record for PK = assetUsageId operationId: getAssetUsage responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/PutAssetUsageSuccessResponse' 204: description: assetUsage not found headers: requestId: description: request id schema: type: string format: uuid requested: description: timestamp of the request schema: type: string format: date-time assetUsageId: description: UID key to assetUsage in IRI or URI format schema: type: string status: description: saying that the assetUsage record not found schema: type: string default: "assetUsage not found" 402: description: denied assetUsage. At least one assetUsage has usageEntitled = false. - If usageEntitled = false, assetUsageDenial is provided for that assetUsage - If usageEntitled = true, entitlement is provided for that assetUsage content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/AssetUsageResponse' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # /api/v1/asset-usage-event: parameters: - name: assetUsageId required: true example: 38935f5c-293b-4e00-91ad-14d5de66eee3 in: query description: UID key to assetUsage in IRI or URI format schema: type: string put: tags: ["asset-usage"] description: notification of asset-usage event to be tracked by LUM with no decision on the entitlement of the action operationId: recordAssetUsageEvent requestBody: description: notification of asset-usage event to be tracked by LUM with no decision on the entitlement of the action required: true content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/AssetUsageEventRequest' responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/AssetUsageEventResponse' get: tags: ["asset-usage"] description: notification of asset-usage event to be tracked by LUM with no decision on the entitlement of the action operationId: getAssetUsageEvent responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/AssetUsageEventResponse' 204: description: assetUsageEvent not found headers: requestId: description: request id schema: type: string format: uuid requested: description: timestamp of the request schema: type: string format: date-time assetUsageId: description: UID key to assetUsage in IRI or URI format schema: type: string status: description: saying that the assetUsage record not found schema: type: string default: "assetUsageEvent not found" # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # /api/v1/asset-usage-tracking/software-licensor: parameters: - name: softwareLicensorId required: true example: Company A in: query description: identifier of the entity that issued the licenseProfile schema: type: string - name: startDateTime example: "2020-01-30T20:45:01.123Z" in: query description: start date-time or date of the asset-usage request to filter the results by. It is optional and the filtering is inclusive (startDateTime<=requested) schema: type: string format: date-time - name: endDateTime example: "2020-01-31T23:02:01.310Z" in: query description: end date-time or date of the asset-usage request to filter the results by. It is optional and the filtering is inclusive (requested<=endDateTime) - When date is provided in the query, it is converted to the maximal date-time of the same date in GMT time zone. For instance, '2020-03-19' converted to '2020-03-19T23:59:59.999Z' schema: type: string format: date-time get: tags: ["asset-usage-tracking"] operationId: getAssetUsageTracking description: returns all assetUsage request records for supplier softwareLicensorId responses: 200: description: success content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/GetAssetUsageTrackingResponse' 400: description: invalid input data content: 'application/json; charset=utf-8': schema: $ref: '#/components/schemas/ErrorResponse' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # components: schemas: BaseRequestTop: description: base request header properties: requestId: description: GUID unique identifier of the request type: string format: uuid requested: description: timestamp of the request type: string format: date-time RequestTopUser: description: request and response header type: object required: - userId properties: userId: description: identifier of the user type: string example: "alex" RequestTopSwSystem: description: request and response header type: object required: - swMgtSystemId properties: swMgtSystemId: description: system that manages the software pieces and sent the request type: string example: Acumos swMgtSystemInstanceId: description: system instance id that manages the software pieces and sent the request type: string example: "Acumos#22" swMgtSystemComponent: description: component inside the system that sent the request example: "model-runner" RequestTopAction: description: request and response header type: object required: - action properties: action: description: requested action on the asset like download, publish, execute, ... type: string example: "acumos:download" # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # Healthcheck: description: healthcheck info required: [healthcheck] properties: healthcheck: properties: serverName: description: LUM - License Usage Manager type: string default: "lum-server" serverVersion: description: version of software running on this server type: string apiVersion: description: version of API supported by this server type: string nodeVersion: description: version of node.js this server runs under type: string databaseInfo: description: info of postgres database this server runs with properties: pgVersion: description: version of postgres database this server runs with type: string databaseVersion: description: version of LUM database this server runs with - expected to match to serverVersion type: string schemaCreated: description: date-time when LUM schema was created - inited type: string format: date-time schemaModified: description: date-time when LUM schema was modified type: string format: date-time databaseStarted: description: date-time when LUM database server started type: string format: date-time databaseUptime: description: uptime of the LUM database server type: string checked: description: date-time when got database info type: string format: date-time serverRunInstanceId: description: identifier of the running instance of the server type: string format: uuid serverStarted: description: when the instance of the server started to run type: string format: date-time serverUptime: description: how long the instance of the server running type: string pathToOpenapiUi: description: path for the openapi-ui endpoint that contains links to API resources type: string example: serverName: "lum-server" serverVersion: "0.0.0" apiVersion: "0.0.0" nodeVersion: "12.18.1" databaseInfo: pgVersion: "PostgreSQL 11.5 on x86_64-pc-linux-musl, compiled by gcc (Alpine 8.3.0) 8.3.0, 64-bit" databaseVersion: "0.0.0" schemaCreated: "2020-01-09T17:12:31.791Z" schemaModified: "2020-01-09T17:12:31.791Z" databaseStarted: "2020-01-09T17:12:32.361Z" databaseUptime: "00:22:38.660894" checked: "2020-01-09T17:35:11.022Z" serverRunInstanceId: "faa08408-59fd-44d2-b815-9ceb9b8fdf92" serverStarted: "2020-01-09T17:33:35.001Z" serverUptime: "00:01:36.095038" pathToOpenapiUi: "/ui/openapi" HealthcheckResponse: description: request to revoke any record to conatin the userId allOf: - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/Healthcheck' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # ErrorBody: description: error from lum-server properties: error: description: error from lum-server type: object example: code: "trouble" message: "trouble happened" ErrorResponse: description: error from lum-server that also contains the healthcheck allOf: - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/ErrorBody' - $ref: '#/components/schemas/Healthcheck' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # SwTagIdTop: description: swTagId on top type: object required: - swTagId properties: swTagId: description: globally unique identifier of the software tag up to its version (in Acumos it is revisionId) possible format _ like "c0de3e70-e815-461f-9734-a239c450bf77_7.5.3.123-t1" type: string example: "0bde3cf2-7a91-40ff-af5f-2d314e677e6a" SWIDCreators: description: collection of creators for swidTag type: object required: [swCreators] properties: swCreators: description: collection of userId values of the creators for swidTag type: array default: [] items: type: string SetSwidTagCreatorsRequest: description: request to set swidTag Creators allOf: - $ref: '#/components/schemas/RequestTopUser' - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/SwTagIdTop' - $ref: '#/components/schemas/SWIDCreators' SetSwidTagCreatorsResponse: description: response to update the creators on swidTag request allOf: - $ref: '#/components/schemas/RequestTopUser' - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/SWIDResponse' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # SWIDBody: description: software identifying tag info type: object required: - swTagId - swPersistentId - swVersion - licenseProfileId - softwareLicensorId properties: swTagId: description: globally unique identifier of the software tag up to its version (in Acumos it is revisionId) possible format _ type: string example: "f36b925c-618f-4284-a8d7-650d4e41fcbb" swPersistentId: description: versionless product-id (in Acumos it is solutionId) type: string format: uuid example: "c0de3e70-e815-461f-9734-a239c450bf77" swVersion: description: version of the software piece possible format semver example "7.5.3.123-t1" type: string swVersionComparable: description: comparable version of the software piece format padded semver for string-like ordering of versions example "00000007.00000005.00000003.00000123-t00000001" type: string licenseProfileId: description: identifier of the public license for the software piece FK to licenseProfile type: string format: uuid example: "2f3cc0aa-5a15-416a-80c6-76ba0c9e1a67" softwareLicensorId: description: identifier of the entity that issued the licenseProfile type: string example: Company A swCategory: description: image processing, software, image, video, data. - used for matching to the right-to-use type: string nullable: true swCatalogs: description: array of catalog info the software is stored in Acumos type: array default: [] nullable: true items: type: object properties: swCatalogId: description: uid for the catalog identifier - used for matching to the right-to-use type: string swCatalogType: description: restricted, company-wide, public, etc. - used for matching to the right-to-use type: string swProductName: description: name of the software product type: string example: example-model swidTagDetails: description: more details on software identifying tag type: object properties: edition: description: edition like Home, Pro, Entierprise type: string revision: description: revision of the software type: string marketVersion: description: version on the market can differ from internal version type: string patch: description: whether this is a patch type: boolean productUrl: description: url to find more about this software type: string format: url SWIDHousekeeping: description: properties populated by LUM server properties: swidTagRevision: description: 1,2,3,... revision of the swidTag - updates are allowed - auto-incremented by LUM type: integer format: int64 swidTagActive: description: whether swidTag is not revoked-closed type: boolean creator: description: userId of the creator type: string created: description: date-time-stamp for the record creation type: string format: date-time modifier: description: userId of the modifier type: string modified: description: date-time-stamp for the record update type: string format: date-time closer: description: userId of the closer type: string closed: description: date-time-stamp of the record closure type: string format: date-time closureReason: description: reason for the closure - revoked, expired, etc. type: string SWIDRequest: description: request to put swidTag type: object required: [swidTag] properties: swidTag: $ref: '#/components/schemas/SWIDBodyAndCreator' SWIDBodyAndCreator: description: swidTag and Swid tag creator owner allOf: - $ref: '#/components/schemas/SWIDBody' - $ref: '#/components/schemas/SWIDCreators' SWIDResponse: description: response to swidTag request type: object required: [swidTag] properties: swidTag: $ref: '#/components/schemas/SWIDBodyCreatorHousekeeping' SWIDBodyCreatorHousekeeping: description: swidTag and Swid tag creator owner and house keeping allOf: - $ref: '#/components/schemas/SWIDBody' - $ref: '#/components/schemas/SWIDCreators' - $ref: '#/components/schemas/SWIDHousekeeping' SWIDRevokedResponse: description: response to revoke the swidTag type: object required: - status - swidTag properties: swTagId: description: globally unique identifier of the software tag up to its version (in Acumos it is revisionId) type: string status: description: status of swidTag revoking type: string default: "swidTag revoked" GetSwidTagResponse: description: response to swidTag request allOf: - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/SWIDResponse' - $ref: '#/components/schemas/LicenseProfileResponse' PutSwidTagRequest: description: request to set swidTag allOf: - $ref: '#/components/schemas/RequestTopUser' - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/SWIDRequest' - $ref: '#/components/schemas/LicenseProfileRequest' PutSwidTagResponse: description: response to swidTag request allOf: - $ref: '#/components/schemas/RequestTopUser' - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/SWIDResponse' - $ref: '#/components/schemas/LicenseProfileResponse' RevokeSwidTagResponse: description: response to revoke the swidTag allOf: - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/SWIDRevokedResponse' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # GetActiveSwidTagsResponse: description: response to GET swid-tags allOf: - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/ActiveSwidTags' ActiveSwidTags: description: collection of keys for the active swidTags required: [activeSwidTags] properties: activeSwidTags: description: collection of keys for the active swidTags type: array default: [] nullable: true items: description: slim info (keys) on single active swidTag with license type: object required: - softwareLicensorId - swTagId - swidTagRevision - swPersistentId - swVersion - swProductName - licenseProfileId - licenseProfileRevision - licenseProfileActive - isRtuRequired properties: softwareLicensorId: description: supplier or owner of the software type: string example: Company A swTagId: description: globally unique identifier of the software tag up to its version (in Acumos it is revisionId) type: string example: "c8606a77-c39d-4060-bd7d-1051f4c6d316" swidTagRevision: description: 1,2,3,... revision of the swidTag - updates are allowed - auto-incremented by LUM type: integer format: int64 example: 5 swPersistentId: description: versionless product-id (in Acumos it is solutionId) type: string format: uuid example: "c0de3e70-e815-461f-9734-a239c450bf77" swVersion: description: version of the software piece possible format semver example "7.5.3.123-t1" type: string swProductName: description: name of the software product type: string example: example-model licenseProfileId: description: GUID FK to licenseProfile type: string format: uuid example: "c75ddb24-0410-49f4-8550-98b06f9a0a51" licenseProfileRevision: description: 1,2,3,... revision of the licenseProfile type: integer format: int64 example: 5 licenseProfileActive: description: whether the license profile is currently active - not revoked type: boolean isRtuRequired: description: whether requires the right-to-use for usage, when false goes directly to usageMetrics type: boolean # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # GetEntitledSwidTagsResponse: description: response to GET swid-tags/available-entitlement allOf: - $ref: '#/components/schemas/RequestTopUser' - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/RequestTopAction' - $ref: '#/components/schemas/SwidTagsWithAvailableEntitlement' SwidTagsWithAvailableEntitlement: description: collection of keys for the swidTags with available-entitlement for the userId and action required: [swidTagsWithAvailableEntitlement] properties: swidTagsWithAvailableEntitlement: description: collection of keys for the swidTags with available-entitlement for the userId and action type: array default: [] nullable: true items: description: slim info (keys) on single swidTag with availableEntitlement type: object required: - softwareLicensorId - swTagId - swidTagRevision - swPersistentId - swVersion - swProductName - licenseProfileId - licenseProfileRevision - isUsedBySwCreator - isRtuRequired properties: softwareLicensorId: description: supplier or owner of the software type: string example: Company A swTagId: description: globally unique identifier of the software tag up to its version (in Acumos it is revisionId) type: string example: "c8606a77-c39d-4060-bd7d-1051f4c6d316" swidTagRevision: description: 1,2,3,... revision of the swidTag - updates are allowed - auto-incremented by LUM type: integer format: int64 example: 5 swPersistentId: description: versionless product-id (in Acumos it is solutionId) type: string format: uuid example: "c0de3e70-e815-461f-9734-a239c450bf77" swVersion: description: version of the software piece possible format is a semver like "7.5.3.123-t1" type: string example: "1.2.3" swProductName: description: name of the software product type: string example: example-model licenseProfileId: description: GUID FK to licenseProfile type: string format: uuid example: "c75ddb24-0410-49f4-8550-98b06f9a0a51" licenseProfileRevision: description: 1,2,3,... revision of the licenseProfile type: integer format: int64 example: 5 isUsedBySwCreator: description: whether the userId listed in swCreators of the software type: boolean example: false isRtuRequired: description: whether requires the right-to-use for usage, when false goes directly to usageMetrics type: boolean example: true availableEntitlement: $ref: '#/components/schemas/AssetUsageEntitlementBody' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # LicenseProfile: description: terms and conditions define the rights for the usage of software asset type: object required: - licenseProfileId - isRtuRequired properties: licenseProfileId: description: identifier of the software licenseProfile -- FK to licenseProfile type: string format: uuid licenseProfile: description: full body of the license profile type: object isRtuRequired: description: whether requires the right-to-use for usage, when false goes directly to usageMetrics type: boolean default: true licenseTxt: description: license.txt - humanly readable terms and conditions for the licenseProfile type: string licenseName: description: name of the license in free text type: string licenseDescription: description: description of the license in free text type: string licenseNotes: description: any textual notes type: string LicenseProfileHousekeeping: description: properties populated by LUM server properties: licenseProfileRevision: description: 1,2,3,... revision of the licenseProfile - updates are allowed - auto-incremented by LUM type: integer format: int64 licenseProfileActive: description: whether the license profile is currently active - not revoked type: boolean default: true creator: description: userId of the creator type: string created: description: date-time-stamp for the record creation type: string format: date-time modifier: description: userId of the modifier type: string modified: description: date-time-stamp for the record update type: string format: date-time closer: description: userId of the closer type: string closed: description: date-time-stamp of the record closure type: string format: date-time closureReason: description: reason for the closure - revoked, expired, etc. type: string LicenseProfileRequest: description: license data for licenseProfile record type: object required: [licenseProfile] properties: licenseProfile: $ref: '#/components/schemas/LicenseProfile' LicenseProfileResponse: description: license data for licenseProfile record type: object required: [licenseProfile] properties: licenseProfile: $ref: '#/components/schemas/LicenseProfileHouseKeepingMixin' LicenseProfileHouseKeepingMixin: description: swidTag and Swid tag creator owner and house keeping type: object allOf: - $ref: '#/components/schemas/LicenseProfile' - $ref: '#/components/schemas/LicenseProfileHousekeeping' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # AssetUsageAgreementTop: description: data for assetUsageAgreement record and rights-to-use under that required: - assetUsageAgreement properties: assetUsageAgreement: description: assetUsageAgreement body required: - softwareLicensorId - assetUsageAgreementId properties: softwareLicensorId: description: supplier or owner of the software type: string example: Company A assetUsageAgreementId: description: UID key to assetUsageAgreement in IRI or URI format example: "acumos://software-licensor/Company A/agreement/3eb8c43a-bf19-46ab-8392-99c7efdf4106" type: string AssetUsageAgreement: description: data for assetUsageAgreement record and rights-to-use under that required: - assetUsageAgreement properties: assetUsageAgreement: description: assetUsageAgreement body required: - agreement properties: agreement: description: ODRL based agreement data - https://www.w3.org/TR/odrl-model/#policy-agreement $ref: '#/components/schemas/ODRLAgreement' GroomedAgreement: description: LUM returns the result of grooming the ODRL agreement+agreementRestriction required: - assetUsageAgreement properties: assetUsageAgreement: description: assetUsageAgreement body required: - groomedAgreement properties: groomedAgreement: description: groomed full body of ODRL agreement with restriction already applied. The groomedAgreement is not in ODRL format, but organized for LUM logic. The only purpose of this field in API is debugging - do not put any logic based on groomedAgreement AssetUsageAgreementHousekeeping: description: properties populated by LUM server required: - assetUsageAgreement properties: assetUsageAgreement: description: assetUsageAgreement body properties: assetUsageAgreementRevision: description: 1,2,3,... revision of the AssetUsageAgreement - updates are allowed - auto-incremented by LUM type: integer format: int64 assetUsageAgreementActive: description: whether swidTag is not revoked-closed type: boolean creator: description: userId of the creator type: string created: description: date-time-stamp for the record creation type: string format: date-time modifier: description: userId of the modifier type: string modified: description: date-time-stamp for the record update type: string format: date-time closer: description: userId of the closer type: string closed: description: date-time-stamp of the record closure type: string format: date-time closureReason: description: reason for the closure - revoked, expired, etc. type: string AgreementRevokedResponse: description: response to revoke the agreement type: object required: - softwareLicensorId - assetUsageAgreementId - status properties: softwareLicensorId: description: supplier or owner of the software type: string example: Company A assetUsageAgreementId: description: UID key to assetUsageAgreement in IRI or URI format type: string status: description: status of assetUsageAgreement revoking type: string default: "assetUsageAgreement revoked" GetAssetUsageAgreementResponse: description: response to assetUsageAgreement request allOf: - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/AssetUsageAgreementTop' - $ref: '#/components/schemas/AssetUsageAgreement' - $ref: '#/components/schemas/AssetUsageAgreementRestriction' - $ref: '#/components/schemas/GroomedAgreement' - $ref: '#/components/schemas/AssetUsageAgreementHousekeeping' PutAssetUsageAgreementRequest: description: request to set assetUsageAgreement allOf: - $ref: '#/components/schemas/RequestTopUser' - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/AssetUsageAgreementTop' - $ref: '#/components/schemas/AssetUsageAgreement' PutAssetUsageAgreementResponse: description: response to assetUsageAgreement request allOf: - $ref: '#/components/schemas/RequestTopUser' - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/AssetUsageAgreementTop' - $ref: '#/components/schemas/AssetUsageAgreement' - $ref: '#/components/schemas/AssetUsageAgreementRestriction' - $ref: '#/components/schemas/GroomedAgreement' - $ref: '#/components/schemas/AssetUsageAgreementHousekeeping' RevokeAgreementResponse: description: response to revoke the assetUsageAgreement allOf: - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/AgreementRevokedResponse' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # AssetUsageAgreementRestriction: description: data for assetUsageAgreementRestriction record with all the subscriber company restrictions required: - assetUsageAgreement properties: assetUsageAgreement: description: assetUsageAgreement body required: - agreementRestriction properties: agreementRestriction: description: ODRL based assetUsageAgreementRestriction data - https://www.w3.org/TR/odrl-model/#policy-agreement $ref: '#/components/schemas/ODRLAgreement' PutAssetUsageAgreementRestrictionRequest: description: request to set assetUsageAgreementRestriction allOf: - $ref: '#/components/schemas/RequestTopUser' - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/AssetUsageAgreementTop' - $ref: '#/components/schemas/AssetUsageAgreementRestriction' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # AssetUsageResponseTop: description: base response for assetUsage and assetUsageReq type: object required: - assetUsageReqId properties: assetUsageReqId: description: UID identifier of request that inserted the assetUsageHistory type: string IncludedAssetUsageTop: description: asset-usage of a single included asset type: object required: - includedSwTagId - includedAssetUsageId properties: includedSwTagId: description: | globally unique identifier of the software tag up to its version that is included by or composed into the current software piece. (in Acumos it is revisionId) type: string includedAssetUsageId: description: | unique identifier of the asset-usage record for the software asset that is included by or composed into the current software asset. UID key to assetUsage in IRI or URI format type: string nullable: true AssetUsageRequestTop: description: request for entitlement on the assetUsage or to record the asset-usage event type: object required: - swTagId - assetUsageId - action properties: swTagId: description: globally unique identifier of the software tag up to its version (in Acumos it is revisionId) type: string example: "0bde3cf2-7a91-40ff-af5f-2d314e677e6a" assetUsageId: description: UID key to assetUsage in IRI or URI format - either provide your own value that uniquely identifies the asset-usage or send the value from the previous successful assetUsage request for the current asset type: string nullable: true action: description: requested action on the asset like download, publish, execute, ... type: string example: "acumos:deploy" AssetUsageIncludedRequestTop: description: request for entitlement on the included assetUsage type: object properties: isIncludedAsset: description: included asset (true), master asset (false). optional parameter to indicate that the asset is included into other assetUsage. isIncludedAsset = true can be provided when includedAssetUsage part is absent type: boolean default: false nullable: true includedAssetUsage: description: list of included swTagId and asset-usage-ids type: array default: [] nullable: true items: $ref: '#/components/schemas/IncludedAssetUsageTop' AssetUsageRequest: description: request for entitlement on the assetUsage type: object required: [assetUsageReq] properties: assetUsageReq: description: request for entitlement on the assetUsage $ref: '#/components/schemas/AssetUsageRequestTopMixin' AssetUsageRequestTopMixin: description: mixin for asset usage request type: object allOf: - $ref: '#/components/schemas/AssetUsageRequestTop' - $ref: '#/components/schemas/AssetUsageIncludedRequestTop' AssetUsageEventBody: description: body of the notification of asset-usage event to be tracked by LUM with no decision on the entitlement of the action type: object required: [event] properties: event: description: any object that contains the event details type: object nullable: false example: hello: world AssetUsageEvent: description: notification of asset-usage event to be tracked by LUM with no decision on the entitlement of the action type: object required: [assetUsageEvent] properties: assetUsageEvent: description: notification of asset-usage event to be tracked by LUM with no decision on the entitlement of the action $ref: '#/components/schemas/AssetUsageEventMixin' AssetUsageEventMixin: description: Asset usage event mixin type: object allOf: - $ref: '#/components/schemas/AssetUsageRequestTop' - $ref: '#/components/schemas/AssetUsageEventBody' AssetUsageEventSeqResponse: description: send back the assetUsageSeq in assetUsageEvent required: [assetUsageEvent] properties: assetUsageEvent: description: adding assetUsageSeq into assetUsageEvent properties: softwareLicensorId: description: supplier or owner of the software type: string example: Company A swidTagRevision: description: 1,2,3,... revision of the swidTag - updates are allowed - auto-incremented by LUM type: integer format: int64 licenseProfileId: description: GUID FK to licenseProfile type: string format: uuid licenseProfileRevision: description: 1,2,3,... revision of the licenseProfile type: integer format: int64 isRtuRequired: description: whether requires the right-to-use for usage, when false goes directly to usageMetrics type: boolean default: true assetUsageSeq: description: sequential number of the asset-usage for the assetUsageId type: integer format: int64 ReqUsageEntitled: description: response to assetUsageReq request for the whole request properties: usageEntitled: description: whether the action on the request has been entitled (true) or not (false) by LUM type: boolean AssetUsageEntitled: description: response to assetUsageReq request per each assetUsage properties: usageEntitled: description: whether the action on specific assetUsage has been entitled (true) or not (false) by LUM type: boolean isUsedBySwCreator: description: whether the userId listed in swCreators of the software type: boolean default: false assetUsageSeq: description: sequential number of the asset-usage for the assetUsageId type: integer format: int64 swidTagRevision: description: 1,2,3,... revision of the swidTag - updates are allowed - auto-incremented by LUM type: integer format: int64 licenseProfileId: description: GUID FK to licenseProfile type: string format: uuid licenseProfileRevision: description: 1,2,3,... revision of the licenseProfile type: integer format: int64 isRtuRequired: description: whether requires the right-to-use for usage, when false goes directly to usageMetrics type: boolean default: true softwareLicensorId: description: supplier or owner of the software type: string example: Company A AssetUsageResponseBase: description: response to assetUsageReq request type: object required: [assetUsage] properties: assetUsage: description: assetUsage info $ref: '#/components/schemas/AssetUsageEntitledMixin' AssetUsageEntitledMixin: description: AssetUsageEntitledMixin allOf: - $ref: '#/components/schemas/AssetUsageRequestTop' - $ref: '#/components/schemas/AssetUsageEntitled' AssetUsageEntitlementBody: description: asset usage entitlement details properties: rightToUseId: description: uid for the rightToUse that is permission type: string example: "acumos://software-licensor/Company A/permission/98378924-84ff-41f5-87ac-02fd2012c727" rightToUseRevision: description: 1,2,3,... revision of the rightToUse - auto-incremented by LUM type: integer format: int64 example: 3 assetUsageAgreementId: description: UID key to assetUsageAgreement in IRI or URI format. FK to assetUsageAgreement type: string example: "acumos://software-licensor/Company A/agreement/3eb8c43a-bf19-46ab-8392-99c7efdf4106" assetUsageAgreementRevision: description: 1,2,3,... revision of the AssetUsageAgreement - updates are allowed - auto-incremented by LUM type: integer format: int64 example: 3 licenseKeys: description: list of licenseKey values type: array default: [] items: description: licenseKey is provided by supplier in the right-to-use and consumed by the software to unlock the functionality type: string AssetUsageEntitlement: description: entitled response to assetUsageReq request per single asset-usage type: object properties: entitlement: $ref: '#/components/schemas/AssetUsageEntitlementBody' IncludedAssetUsageSuccess: description: entitled response to assetUsageReq request for included asset-usage type: object properties: includedAssetUsage: description: list of included swTagId and asset-usage-ids type: array default: [] nullable: true items: $ref: '#/components/schemas/IncludedAssetUsageMixin' IncludedAssetUsageMixin: allOf: - $ref: '#/components/schemas/IncludedAssetUsageTop' - $ref: '#/components/schemas/AssetUsageEntitled' - $ref: '#/components/schemas/AssetUsageEntitlement' AssetUsageSuccessResponse: description: entitled response to assetUsageReq request type: object required: [assetUsage] properties: assetUsage: description: assetUsage info $ref: '#/components/schemas/AssetUsageSuccessMixin' AssetUsageSuccessMixin: allOf: - $ref: '#/components/schemas/AssetUsageEntitlement' - $ref: '#/components/schemas/IncludedAssetUsageSuccess' AssetUsageDenial: description: denials for the response to assetUsageReq request type: object properties: assetUsageDenialSummary: description: human readable summary for denial of the asset-usage type: string example: "swid-tag(ee48b699-3b16-4391-884c-1bec557f32b9) has been found but asset-usage is prohibited by prohibition(acumos://software-licensor/Company A/permission/98378924-84ff-41f5-87ac-02fd2012c727) under asset-usage-agreement(acumos://software-licensor/Company A/agreement/3eb8c43a-bf19-46ab-8392-99c7efdf4106) for action(acumos:deploy)" assetUsageDenial: description: collection of denial info to assetUsageReq request type: array default: [] nullable: true items: description: single denial info type: object required: - denialCode - denialType - denialReason properties: denialCode: description: unique code for the reason of denial. Use denialCode value to construct the denial message from other parts of denial beside the denialReason type: string enum: - denied_due_swidTagNotFound - denied_due_swidTagRevoked - denied_due_licenseProfileNotFound - denied_due_licenseProfileRevoked - denied_due_agreementNotFound - denied_due_rightToUseRevoked - denied_due_usageProhibited - denied_due_countUniqueUsersOnAssignee - denied_due_usersOnAssignee - denied_due_swPersistentIdOnTarget - denied_due_swTagIdOnTarget - denied_due_swProductNameOnTarget - denied_due_swCategoryOnTarget - denied_due_swCatalogIdOnTarget - denied_due_swCatalogTypeOnTarget - denied_due_expireOn - denied_due_goodFor - denied_due_enableOn - denied_due_usageCount denialType: description: type of the reason for denial. It can contain one or many values of denialCode type: string enum: - swidTagNotFound - swidTagRevoked - licenseProfileNotFound - licenseProfileRevoked - agreementNotFound - rightToUseRevoked - usageProhibited - matchingConstraintOnAssignee - matchingConstraintOnTarget - timingConstraint - usageConstraint denialReason: description: human readable explanation why the entitlement was denied. It consumes all other parts of denial type: string deniedAction: description: either requested action on the asset like download, publish, execute, etc. or special value of use type: string deniedAssetUsageAgreementId: description: uid of Asset-Usage-AssetUsageAgreement that caused the denial or not match type: string deniedAssetUsageAgreementRevision: description: 1,2,3,... revision of the AssetUsageAgreement type: integer format: int64 deniedRightToUseId: description: id of rightToUse that caused the denial type: string deniedRightToUseRevision: description: 1,2,3,... revision of the rightToUse - auto-incremented by LUM type: integer format: int64 denialReqItemName: description: name of the item that came from req or NOW() type: string denialReqItemValue: description: value of the item that came from req or NOW() It can be either string or number deniedConstraint: description: data from usageConstraint or assignee refinement record that caused the denial type: object deniedConstraintInvalid: description: whether the denied constraint is invalid (true) or valid (false). It is invalid when rightOperand == null. When this is true, the asset-usage-agreement contains error on this constraint type: boolean deniedMetrics: description: current statistical data that caused the denial. It is optional and its structure can very type: object example: denialCode: denied_due_usageProhibited denialType: usageProhibited denialReason: "swid-tag(ee48b699-3b16-4391-884c-1bec557f32b9) has been found but asset-usage is prohibited by prohibition(acumos://software-licensor/Company A/permission/98378924-84ff-41f5-87ac-02fd2012c727) under asset-usage-agreement(acumos://software-licensor/Company A/agreement/3eb8c43a-bf19-46ab-8392-99c7efdf4106) for action(acumos:deploy)" deniedAction: "acumos:deploy" deniedAssetUsageAgreementId: "acumos://software-licensor/Company A/agreement/3eb8c43a-bf19-46ab-8392-99c7efdf4106" deniedAssetUsageAgreementRevision: 19 deniedRightToUseId: "acumos://software-licensor/Company A/permission/98378924-84ff-41f5-87ac-02fd2012c727" deniedRightToUseRevision: 19 denialReqItemName: action denialReqItemValue: "acumos:deploy" deniedConstraint: action: "acumos:deploy" AssetUsageDenialOrEntitlement: description: either denial or entitlement for denied response to assetUsageReq request. - If usageEntitled = false, assetUsageDenial is provided for that assetUsage - If usageEntitled = true, entitlement is provided for that assetUsage # oneOf: allOf: - $ref: '#/components/schemas/AssetUsageEntitlement' - $ref: '#/components/schemas/AssetUsageDenial' # discriminator: # propertyName: usageEntitled PutAssetUsageRequest: description: request for entitlement on assetUsage allOf: - $ref: '#/components/schemas/RequestTopUser' - $ref: '#/components/schemas/RequestTopSwSystem' - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/AssetUsageRequest' PutAssetUsageSuccessResponse: description: response to assetUsage request allOf: - $ref: '#/components/schemas/RequestTopUser' - $ref: '#/components/schemas/RequestTopSwSystem' - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/ReqUsageEntitled' - $ref: '#/components/schemas/AssetUsageResponseBase' - $ref: '#/components/schemas/AssetUsageSuccessResponse' AssetUsageResponse: description: response to assetUsage request on denial - either denial or entitlement per each asset allOf: - $ref: '#/components/schemas/RequestTopUser' - $ref: '#/components/schemas/RequestTopSwSystem' - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/ReqUsageEntitled' - $ref: '#/components/schemas/AssetUsage' AssetUsage: description: AssetUsage record type: object required: [assetUsage] properties: assetUsage: $ref: '#/components/schemas/AssetUsageEntitledMixinAndDenialOrEntitlementAndIncludedAssetUsage' AssetUsageEntitledMixinAndDenialOrEntitlementAndIncludedAssetUsage: description: mixin for assetUsage EntitledMixin AND assetUsage DenialOrEntitlement AND IncludedAssetUsage type: object allOf: - $ref: '#/components/schemas/AssetUsageEntitledMixin' - $ref: '#/components/schemas/AssetUsageDenialOrEntitlement' - type: object properties: includedAssetUsage: description: list of included swTagId and assetUsageId type: array default: [] nullable: true items: allOf: - $ref: '#/components/schemas/IncludedAssetUsageTop' - $ref: '#/components/schemas/AssetUsageEntitled' - $ref: '#/components/schemas/AssetUsageDenialOrEntitlement' AssetUsageEventRequest: description: notification of asset-usage event to be tracked by LUM with no decision on the entitlement of the action allOf: - $ref: '#/components/schemas/RequestTopUser' - $ref: '#/components/schemas/RequestTopSwSystem' - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/AssetUsageEvent' AssetUsageEventResponse: description: response to assetUsageEvent request allOf: - $ref: '#/components/schemas/RequestTopUser' - $ref: '#/components/schemas/RequestTopSwSystem' - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/AssetUsageEvent' - $ref: '#/components/schemas/AssetUsageEventSeqResponse' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # GetAssetUsageTrackingResponse: description: returns all assetUsage request records for supplier softwareLicensorId type: object required: - title - softwareLicensorId - stats - assetUsages - assetUsageEvents properties: title: description: title of the report type: string example: assetUsage tracking records for supplier softwareLicensorId softwareLicensorId: description: supplier or owner of the software type: string example: Company A startDateTime: description: start date-time of the asset-usage request to filter the results by. It is optional and the filtering is inclusive (startDateTime<=requested) type: string format: date-time example: "2020-01-30T20:45:01.123Z" endDateTime: description: end date-time of the asset-usage request to filter the results by. It is optional and the filtering is inclusive (requested<=endDateTime). - When date is provided in the query, it is converted to the maximal date-time of the same date. For instance, '2020-03-19' converted to '2020-03-19T23:59:59.999Z' type: string format: date-time example: "2020-01-31T23:02:01.310Z" stats: description: statistics of found assetUsages and assetUsageEvents properties: assetUsages: description: statistics of found assetUsages properties: count: description: count of found assetUsages type: integer example: 2 minDateTime: description: minimal value of "requested" field in found assetUsages type: string format: date-time example: "2020-01-30T20:46:10.531Z" maxDateTime: description: maximal value of "requested" field in found assetUsages type: string format: date-time example: "2020-01-30T20:50:22.812Z" assetUsageEvents: description: statistics of found assetUsageEvents properties: count: description: count of found assetUsageEvents type: integer example: 2 minDateTime: description: minimal value of "requested" field in found assetUsageEvents type: string format: date-time example: "2020-01-31T17:11:45.653Z" maxDateTime: description: maximal value of "requested" field in found assetUsageEvents type: string format: date-time example: "2020-01-31T18:08:01.310Z" assetUsages: description: list of either denial or entitlement responses to assetUsageReq request type: array default: [] nullable: true items: $ref: '#/components/schemas/AssetUsageResponse' assetUsageEvents: description: list of asset-usage events type: array default: [] nullable: true items: $ref: '#/components/schemas/AssetUsageEventResponse' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # ODRLConstraint: description: 'ODRL based [constraint](https://www.w3.org/TR/odrl-model/#constraint-class) see [RTU design](https://wiki.acumos.org/pages/viewpage.action?pageId=20547102)' required: - leftOperand - operator - rightOperand properties: leftOperand: description: value to compare versus the expected value - ```count``` is only applicable to permission and not to prohibition. Each action on the permission has its own usage ```count``` that does not depend on the usage ```count``` of other actions. - ```date``` is applicable to both permission and prohibition. The ```operator``` on ```date``` defines whether it is the ```expireOn``` or ```enableOn```. The ```date``` constraint is rule specific - it applies to all the actions on the rule. - ```"lum:goodFor"``` is only applicable to permission and not to prohibition. The ```"lum:goodFor"``` constraint is permission specific - it applies to all the actions on the permission and is counted from the first entitled asset usage of any action. type: string enum: - count - date - "lum:goodFor" operator: description: comparison operator between leftOperand and rightOperand > count and "lum:goodFor" cannot be greater than or greater than or equal to type: string enum: - lt - lteq - eq - gteq - gt rightOperand: description: 'string or stringified number like #### count #### for usage ```count``` constraint: ```"5"``` or ```{"@value": "5", "@type": "xsd:integer"}``` #### date #### for ```date```: ```"2019-08-01"``` or ```{"@value": "2019-08-01", "@type": "xsd:date"}``` to define the expireOn or enableOn timing constraints. > the value of the date is expected to be in ```GMT``` timezone in ISO ```"CCYY-MM-DD"``` format --- #### "lum:goodFor" #### - for ```"lum:goodFor"```: ```"30"``` or ```{"@value": "30"}``` or ```"P30D"``` or ```{"@value": "P30D"}``` to define the time duration when the usage is permitted after the first entitled asset usage of any action was recorded by LUM on the permission. - LUM is using [ISO-8601 for duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) - in addition to ISO-8601 format when the value of the rightOperand is a stringified number, LUM assumes that is the duration in days (default) > For instance, ```"30"``` is converted by LUM to ```"P30D"``` and is ```30 days``` >> ```{ "leftOperand": "lum:goodFor", "operator": "lteq", "rightOperand": "30" }``` is the same as the following ```{ "leftOperand": "lum:goodFor", "operator": "lteq", "rightOperand": "P30D" }``` - **ISO-8601 formats** - always start with ```P``` and put ```T``` to separate date from time - at least one number part is required, but any combination is ok: ```PnYnMnDTnHnMnS```, ```PnW``` >> ```"P30D" = 30 days, "P3Y6M4DT12H30M5S" = 3 years 6 mons 4 days 12:30:05, "P123.5DT23H" = 123 days 35:00:00, "P4.7Y" = 4 years 8 mons, "P1.3M" = 1 mon 9 days, "P1.55W" = 10 days 20:24:00, "P0.5Y" = 6 mons, "PT36H" = 36:00:00, "P1YT5S" = 1 year 00:00:05``` ' type: object ODRLAssigneeRefinement: description: ODRL based [refinement](https://www.w3.org/TR/odrl-model/#constraint-class) see [RTU design](https://wiki.acumos.org/pages/viewpage.action?pageId=20547102) required: - leftOperand - operator - rightOperand properties: leftOperand: description: assignee refinement type: string enum: - "lum:countUniqueUsers" operator: description: comparison operator between leftOperand and rightOperand type: string enum: - "lteq" rightOperand: description: 'maximal counter of unique users - string or stringified number like "5" {"@value": "5", "@type": "xsd:integer"}' example: leftOperand: "lum:countUniqueUsers" operator: "lteq" rightOperand: "5" ODRLAssignee: description: filter the application of permission/prohibition by the users - refinement on assignee - matching constraint on assignee. The ODRL defined source property is not used and is ignored by LUM because the source for LUM is all software-users properties: refinement: description: collection of constraints that limit the selection of the software users type: array default: [] items: $ref: '#/components/schemas/ODRLAssigneeRefinement' ODRLTargetRefinement: description: "ODRL based [refinement on target](https://www.w3.org/TR/odrl-model/#constraint-class) see [RTU design](https://wiki.acumos.org/pages/viewpage.action?pageId=20547102)" required: - leftOperand - operator - rightOperand properties: leftOperand: description: field for refinement type: string enum: - "lum:swPersistentId" - "lum:swTagId" - "lum:swProductName" - "lum:swCategory" - "lum:swCatalogId" - "lum:swCatalogType" operator: description: "lum:in - true when leftOperand value is found in the list of rightOperand" type: string default: "lum:in" enum: - "lum:in" rightOperand: description: array of expected values type: array default: [] items: type: string ODRLTarget: description: filter the application of permission/prohibition by software attributes - refinement on target. The ODRL defined source property is not used and is ignored by LUM because the source for LUM is all software by softwareLicensorId properties: refinement: description: collection of constraints that limit the selection of the software type: array default: [] items: $ref: '#/components/schemas/ODRLTargetRefinement' example: refinement: - leftOperand: "lum:swPersistentId" operator: "lum:in" rightOperand: - "c01c4e06-557c-4c21-bc22-2afd757ee7af" - "cbf31f26-4590-4323-8991-000d9f290901" - leftOperand: "lum:swCategory" operator: "lum:in" rightOperand: - "image-processing" - "face-detection" - leftOperand: "lum:swCatalogId" operator: "lum:in" rightOperand: - "XYZ models" - leftOperand: "lum:swCatalogType" operator: "lum:in" rightOperand: - "restricted" ODRLRule: description: either [permission or prohibition](https://www.w3.org/TR/odrl-model/#rule) required: - uid - action properties: uid: description: unique identifier of type [IRI rfc3987](https://www.w3.org/TR/odrl-vocab/#term-uid). possible format "http://software-licensor//permission/" type: string action: description: 'action on the asset like download, publish, execute, ... in one of the following formats "play" [ "play", "stream" ] {"@type": "Action","@value": "acumos:deploy"} [{"@type": "Action","@value": "acumos:deploy"}, {"@type": "Action","@value": "acumos:download"}]' type: object example: ["acumos:deploy", "acumos:download"] assignee: $ref: '#/components/schemas/ODRLAssignee' target: $ref: '#/components/schemas/ODRLTarget' constraint: description: collection of the usage constraints to a set of assets (e.g. models) all leftOperand count are here and only here type: array default: [] items: $ref: '#/components/schemas/ODRLConstraint' example: - leftOperand: "count" operator: "lteq" rightOperand: "25" - leftOperand: "date" operator: "lteq" rightOperand: "2029-12-31" - leftOperand: "goodFor" operator: "lteq" rightOperand: "30" ODRLAgreement: description: ODRL [agreement](https://www.w3.org/TR/odrl-model/#policy-agreement) required: - uid - assigner - assignee - permission properties: uid: description: the same as assetUsageAgreementId - unique identifier of type [IRI rfc3987](https://www.w3.org/TR/odrl-vocab/#term-uid). possible format "http://software-licensor//agreement/" type: string "@context": description: property to define the processing [context](https://www.w3.org/TR/odrl-vocab/#json-ld). at least the URL "http://www.w3.org/ns/odrl.jsonld" or any other @context (file) including the content of "http://www.w3.org/ns/odrl.jsonld" plus terms defined by a non-ODRL namespace type: object "@type": description: Agreement type: string default: Agreement profile: description: profile that contains non-ODRL defined values type: string assigner: description: the same as softwareLicensorId - identifier of the entity that issued the agreement for right-to-use required: - uid properties: uid: description: the same as softwareLicensorId - identifier of the entity that issued the agreement for right-to-use type: string assignee: $ref: '#/components/schemas/ODRLAssignee' target: $ref: '#/components/schemas/ODRLTarget' permission: description: collection of permissive rules type: array default: [] items: $ref: '#/components/schemas/ODRLRule' prohibition: description: collection of prohibitive rules type: array default: [] items: $ref: '#/components/schemas/ODRLRule' # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # AdminConfigRequest: description: updatable config for LUM server required: [config] properties: config: description: updatable config for LUM server properties: logging: description: updatable config for logging in LUM server properties: logLevel: description: log level in LUM server type: string enum: - error - warn - info - debug logTo: description: collection of loggers to turn off or on in LUM server properties: console: description: logging the dev info to console type: boolean devLog: description: whether to log the dev info into file in LUM's internal format type: boolean healthcheck: description: whether to log the healthcheck into a separate file type: boolean acumos: description: whether to log info in Acumos specific format (json) type: boolean example: config: logging: logLevel: "debug" logTo: devLog: true healthcheck: false acumos: true AdminConfig: description: config for LUM server required: [config] properties: config: description: config for LUM server required: [database] properties: database: description: config of lum-database LUM server properties: user: description: user on lum-database type: string password: description: hex sha256 hash value of password to lum-database. masked format is ***-sha256()*** type: string host: description: hostname of lum-database type: string database: description: database schema inside lum-database type: string port: description: port for lum-database type: integer max: description: maximum number of clients in the pool of connections in LUM server to lum-database type: integer idleTimeoutMillis: description: number of milliseconds a client must sit idle in the pool and not be checked out before it is disconnected from the backend and discarded. type: integer serverName: description: name of the LUM-server service type: string port: description: port for lum-database type: integer maxTxRetryCount: description: maximum number of retries to connect to the database or mitigate the deadlock between the transactions in lum-database type: integer logging: description: logging config in LUM server properties: logLevel: description: log level in LUM server type: string enum: - error - warn - info - debug logTo: description: collection of active loggers in LUM server properties: console: description: logging the dev info to console type: boolean default: true devLog: description: path to dev log file in LUM's internal format. this logger is enabled by non-empty env var $LOGDIR type: string healthcheck: description: path to log file for separate logging of healthcheck queries. this logger is enabled by non-empty env var $LOGDIR type: string acumos: description: path to log file in Acumos specific format (json) type: string example: database: user: lumdb password: "hmac(8e97a9ac003fccfd332b)" host: "lum-database" database: lumdb port: 5432 max: 100 idleTimeoutMillis: 30000 serverName: "lum-server" port: 2080 maxTxRetryCount: 10 logging: logLevel: "debug" logTo: console: true devLog: "/opt/app/lum/logs/dev_lum-server.log" healthcheck: "/opt/app/lum/logs/healthcheck_lum-server.log" acumos: "/opt/app/lum/log-acu/lum-server/lum-server.log" AdminConfigResponse: description: request to revoke any record to conatin the userId allOf: - $ref: '#/components/schemas/BaseRequestTop' - $ref: '#/components/schemas/AdminConfig'