Introduction
OC Reporter comes with its own RESTful API. It can be used to list, modify, create, and remove data through HTTP(s) requests. Currently, not all possibilities available in the GUI are available in the API, but we are extending the API regularly. If you are missing an API endpoint, please contact our Support Team.
Anatomy of an API endpoint
Each API endpoint is structured in the following way:
<url-oc-reporter>/api/workspace/<ws-id>/<action>?_format=json&_token=<token>&_tenant=<ocid>&_language=en
where
- <url-oc-reporter> is the main part of your OC Reporter URL, for example, https://ocreporter.company.com. If you are using the OC Reporter in the Octopus Cloud, then the OC Reporter URL is: https://splareporter2.octopus.cloud
- <ws-id> is the unique ID of the workspace you are using in OC Reporter. To find out the workspace ID, go to your OC Reporter web application and click on the left sidebar under the dropdown WORKSPACE the small link Show workspace details. Copy from Workspace ID field the ID of the workspace.
- <action> is the action you want to execute, for instance listing all virtual machines.
- <token> is your unique API token. In OC Reporter Cloud-based web application, select your name on the top right corner. Click from the list the item My Account and after click My Organisation on the left menu. Copy from the API token field the token. If you are using the OC Reporter on-premises web application, simply open the octopus.json file saved in the installation folder of OC Reporter and copy the token from app.tenant_access_token.
- <ocid> is your unique OCID. Select your name on the top right corner. Click from the list the item My Account and after click My Organisation on the left menu. Copy from the OCID field your OCID value.
Endpoints
The API can deliver the response in JSON or XML format. By default, JSON is used. If you prefer the XML format, you can modify the _format section of the API endpoint to xml instead of json (_format=xml) to get the response in XML format.
If an API endpoint request was successful, you will get a 200 OK status code, otherwise a 404 Not Found if the endpoint was not found, or a 401 Unauthorized status code if there is an issue with the access rights (for instance the API access token is not valid).
The different endpoints below will only describe the <action> part of the endpoint URLs because the rest of the URL is quite static. For List API requests, you have always additionally following parameters available, which can be added in the query part (after the question mark) of the endpoint URL:
- q: Filters the result by the name of the objects.
- page: Defines which page of the listing you want to see.
- showPerPage: Defines how many items per page you want to list.
For Create and Update API requests always ensure to set the Content-Type to application/x-www-form-urlencoded. The relevant data to create or modify are sent in the body section. For instance, if we want to change the name of a customer through the API, we would need to send in the body section the key-value pair: WsCustomer[label]=Customer ABC.
Workspaces
Settings
List all
GET /setting/workspaces
Show one
GET /setting/workspaces/<id>
Show number of assets
GET /setting/workspaces/<id>/assets
Show inventory quality
GET /setting/workspaces/<id>/inventory-quality
List pricecatalog of reseller
GET /pricecatalog/reseller
Update pricecatalog of reseller
PUT /pricecatalog/reseller
To update the pricecatalog of the reseller, use the Pricecatalog key in the body section. Always send the part number and pricecategory of the software license within the body section. The following attributes can be sent:
- Pricecatalog[part_number]=228-05018
- Pricecatalog[price]=3.10
- The purchase price from your reseller
- Pricecatalog[pricecategory]=corporate
- You can choose between corporate, academic, or charity.
Show alerts overview
GET /alert/alerts
Data sources
List all
GET /importer/data-sources
Show one
GET /importer/data-sources/<id>
Infrastructure
Virtual machines
List all
GET /infrastructure/vms
Show one
GET /infrastructure/vms/<id>
Hosts
List all
GET /infrastructure/hosts
Show one
GET /infrastructure/hosts/<id>
Devices
The device endpoints are accessing the same data source as the virtual machine and the host endpoints. The only difference is that in the device endpoints there is no distinguishing between the virtual machines and hosts, both are delivered.
List all
GET /infrastructure/devices
The List endpoint has an extra parameter available that can be used in the query part: payload. The payload parameter can be used to filter out devices by their assigned customers. The following parameters can be used:
- payload[customer.id]: This parameter can be used for filtering devices by the customer ID.
- payload[customer.label]: This parameter can be used for filtering the devices by the customer name.
- payload[customer.internal_id]: This parameter can be used for filtering the devices by the customer’s internal ID, which can be set in the customer detail view in the OC Reporter.
Show one
GET /infrastructure/devices/<id|internal_id|agreement_number>
If you want to show a device by the device internal ID, add additionally the parameter internal=1 to the query part of the endpoint and enter in the action section of the endpoint the internal ID of the device instead of the ID.
If you want to show a device by the device agreement number, add additionally the parameter agreement=1 to the query part of the endpoint and enter in the action section of the endpoint the agreement number of the device instead of the ID.
Create one
POST /infrastructure/devices
To create a new device, use the WsDevice key in the body section. You can use any attribute listed in the Show API request. For instance, you could send the following key-value pairs within the body section:
- WsDevice[label]=Server 1
- WsDevice[type_id]=host or vm
- WsDevice[agreement_number]=124-XYZ
- WsDevice[internal_id]=Xyz
- WsDevice[cluster_id]=4
- WsDevice[cluster_label]=Cluster 1
- WsDevice[host_id]=3
- WsDevice[host_label]=Host 1
- WsDevice[operating_system]=Windows Server Datacenter
- WsDevice[number_cpu]=1
- WsDevice[number_core]=4
- WsDevice[status]=active
Update one
PUT /infrastructure/devices/<id|internal_id|agreement_number>
To update the attributes of a device, use the WsDevice key in the body section. You can update any attribute listed in the Show API request. For instance, if you want to exclude a specific device from SPLA, you could send the following key-value pairs within the body section:
- WsDevice[exclude_spla]=yes
- WsDevice[exclude_spla_reason]=other
- WsDevice[exclude_spla_description]=Server out of SPLA scope
Delete one
DELETE /infrastructure/devices/<id|internal_id|agreement_number>
List performance data
GET /infrastructure/devices/performances
The List performance data endpoint has an extra parameter available that can be used in the query part: payload. The payload parameter can be used for instance to filter out performance data by device. The following parameters can be used:
- payload[device_id]: This parameter can be used for filtering devices by the device ID.
- payload[device_label]: This parameter can be used for filtering devices by the device name.
- payload[observation_start]: This parameter can be used for filtering performance data by the observation start date.
- payload[observation_end]: This parameter can be used for filtering performance data by the observation end date.
List all software by device
GET /infrastructure/devices/<id|internal_id|agreement_number>/softwares
Create one software by device
POST /infrastructure/devices/<id|internal_id|agreement_number>/softwares
To create a new installed software, use the WsInstalledSoftware key in the body section. You can use any attribute listed in the Show API request. For instance, you could send the following key-value pairs within the body section:
- WsInstalledSoftware[label]=My Custom Software
- WsInstalledSoftware[status]=active
Update one software by device
PUT /infrastructure/devices/<id|internal_id|agreement_number>/softwares/<sid>
To update the attributes of installed software, use the WsInstalledSoftware key in the body section. You can update any attribute listed in the Show API request. For instance, if you want to exclude a specific installed software from SPLA, you could send the following key-value pairs within the body section:
- WsInstalledSoftware[exclude_spla]=yes
- WsInstalledSoftware[exclude_spla_reason]=other
- WsInstalledSoftware[exclude_spla_description]=Software out of SPLA scope
Delete one software by device
DELETE /infrastructure/devices/<id|internal_id|agreement_number>/softwares/<sid>
Installed software
List all
GET /infrastructure/installed-softwares
Show one
GET /infrastructure/installed-softwares/<id>
Update one
PUT /infrastructure/installed-softwares/<id>
To update the attributes of installed software, use the WsInstalledSoftware key in the body section. You can update any attribute listed in the Show API request. For instance, if you want to exclude a specific installed software from SPLA, you could send the following key-value pairs within the body section:
- WsInstalledSoftware[exclude_spla]=yes
- WsInstalledSoftware[exclude_spla_reason]=other
- WsInstalledSoftware[exclude_spla_description]=Software out of SPLA scope
Delete one
DELETE /infrastructure/installed-softwares/<id>
Clusters
List all
GET /infrastructure/clusters
Show one
GET /infrastructure/clusters/<id>
Create one
POST /infrastructure/clusters
To create a new cluster, use the WsCluster key in the body section. You can use any attribute listed in the Show API request. For instance, you could send the following key-value pairs within the body section:
- WsCluster[label]=Cluster 1
Update one
PUT /infrastructure/clusters/<id>
To update the attributes of a cluster, use the WsCluster key in the body section. You can update any attribute listed in the Show API request. For instance, if you want to exclude a specific cluster from SPLA, you could send the following key-value pairs within the body section:
- WsCluster[exclude_spla]=yes
- WsCluster[exclude_spla_reason]=other
- WsCluster[exclude_spla_description]=Cluster out of SPLA scope
Delete one
DELETE /infrastructure/clusters/<id>
Datacenters
List all
GET /infrastructure/datacenters
Show one
GET /infrastructure/datacenters/<id>
Scan alerts
List all
GET /infrastructure/scan-alerts
Show one
GET /infrastructure/scan-alerts/<id>
Customers
Users
List all
GET /customer/users
The List endpoint has an extra parameter available that can be used in the query part: payload. The payload parameter can be used to filter out users by their assigned customers. The following parameters can be used:
- payload[customer.id]: This parameter can be used for filtering users by the customer ID.
- payload[customer.label]: This parameter can be used for filtering the users by the customer name.
- payload[customer.internal_id]: This parameter can be used for filtering the users by the customer’s internal ID, which can be set in the customer detail view in the OC Reporter.
Show one
GET /customer/users/<id>
Create one
POST /customer/users
To create a new user, use the WsUser key in the body section. You can use any attribute listed in the Show API request. For instance, you could send the following key-value pairs within the body section:
- WsUser[username]=Username 1
- WsUser[status]=active
Update one
PUT /customer/users/<id>
To update the attributes of a user, use the WsUser key in the body section. You can update any attribute listed in the Show API request. For instance, if you want to exclude a specific user from SPLA, you could send the following key-value pairs within the body section:
- WsUser[exclude_spla]=yes
- WsUser[exclude_spla_reason]=admin
Delete one
DELETE /customer/users/<id>
List all software by user
GET /customer/users/<id>/softwares
Create one software by user
POST /customer/users/<id>/softwares
To create a new user software, use the WsInstalledSoftware key in the body section. You can use any attribute listed in the Show API request. For instance, you could send the following key-value pairs within the body section:
- WsInstalledSoftware[label]=My Custom Software
- WsInstalledSoftware[status]=active
Update one software by user
PUT /customer/users/<id>/softwares/<sid>
To update the attributes of user software, use the WsInstalledSoftware key in the body section. You can update any attribute listed in the Show API request. For instance, if you want to exclude a specific installed software from SPLA, you could send the following key-value pairs within the body section:
- WsInstalledSoftware[exclude_spla]=yes
- WsInstalledSoftware[exclude_spla_reason]=other
- WsInstalledSoftware[exclude_spla_description]=Software out of SPLA scope
Delete one software by user
DELETE /customer/users/<id>/softwares/<sid>
User software
List all
GET /customer/user-softwares
Show one
GET /customer/user-softwares/<id>
Update one
PUT /customer/user-softwares/<id>
To update the attributes of user software, use the WsInstalledSoftware key in the body section. You can update any attribute listed in the Show API request. For instance, if you want to exclude a specific user software from SPLA, you could send the following key-value pairs within the body section:
- WsInstalledSoftware[exclude_spla]=yes
- WsInstalledSoftware[exclude_spla_reason]=other
- WsInstalledSoftware[exclude_spla_description]=Software out of SPLA scope
Delete one
DELETE /customer/user-softwares/<id>
Customers
List all
GET /customer/customers
Show one
GET /customer/customers/<id|internal_id>
If you want to show a customer by the customer internal ID, add additionally the parameter internal=1 to the query part of the endpoint and enter in the action section of the endpoint the internal ID of the customer instead of the ID.
Create one
POST /customer/customers
To create a new customer use the WsCustomer key in the body section. You can set any attribute listed in the Show API request. For instance, if you want to create a customer with a name and an internal ID, you could send the following key-value pairs within the body section:
- WsCustomer[label]=New Customer ABC
- WsCustomer[internal_id]=431319
- WsCustomer[status]=active
Update one
PUT /customer/customers/<id|internal_id>
To update the attributes of a customer, use the WsCustomer key in the body section. You can update any attribute listed in the Show API request. For instance, if you want to modify the customer name and change the customer status, you could send the following key-value pairs within the body section:
- WsCustomer[label]=Customer ABC
- WsCustomer[status]=archived
If you want to update a customer by its internal ID, add additionally to your endpoint the parameter internal=1 and enter in the action section of the endpoint the internal ID of the customer instead of the ID.
Delete one
DELETE /customer/customers/<id|internal_id>
Assign device to customer
PUT /customer/<customer-id>/device/<device-id>
Unassign device from customer
DELETE /customer/<customer-id>/device/<device-id>
Assign user to customer
PUT /customer/<customer-id>/user/<user-id>
Unassign user from customer
DELETE /customer/<customer-id>/user/<user-id>
List pricecatalog of all customers or customer groups
GET /pricecatalog/customers
GET /pricecatalog/customer-groups
List pricecatalog of customer or customer group
GET /pricecatalog/customers/<id|internal_id>
GET /pricecatalog/customer-groups/<id|internal_id>
If you want to list the pricecatalog by the internal ID of the customer, add additionally to your endpoint the parameter internal=1 and enter in the action section of the endpoint the internal ID of the customer instead of the ID.
Update pricecatalog of customer or customer group
PUT /pricecatalog/customers/<id|internal_id>
PUT /pricecatalog/customer-groups/<id|internal_id>
If you want to list the pricecatalog by the internal ID of the customer, add additionally to your endpoint the parameter internal=1 and enter in the action section of the endpoint the internal ID of the customer instead of the ID.
To update the pricecatalog of the customer, use the Pricecatalog key in the body section. Always send the part number of the software license within the body section. The following attributes can be sent:
- Pricecatalog[part_number]=228-05018
- Pricecatalog[price]=3.10
- The sale price to the customer
- Pricecatalog[number_sold]=54
- Number of sold licenses
- Pricecatalog[number_lm]=21
- Number of license mobility
- Pricecatalog[extra_field_1]=Extra info 1
- Custom extra field, which you can use for extra information
- Pricecatalog[extra_field_2]=Extra info 2
- Custom extra field, which you can use for extra information
License mobility expiry of customers
GET /customer/customers/lm-expiry
If you want to list the expired license mobility agreements, add additionally to your endpoint the parameter withEnded=1.
Contract Licenses
In OC Reporter you have the option of entering so-called "contract licences". Contract licences are licences that have already been sold to the customer. Contract licenses are attached to devices. Contract licenses can have start and/or end dates and appear as sold licences in the generated licence reports.
List all by workspace
GET /contract-licenses
List all by customer
GET /contract-licenses/customer/<id|internal_id>
If you want to show a customer by the customer internal ID, add additionally the parameter internal=1 to the query part of the endpoint and enter in the action section of the endpoint the internal ID of the customer instead of the ID.
List all by device
GET /contract-licenses/device/<id|internal_id|agreement_number>
If you want to show a device by the device internal ID, add additionally the parameter internal=1 to the query part of the endpoint and enter in the action section of the endpoint the internal ID of the device instead of the ID.
If you want to show a device by the device agreement number, add additionally the parameter agreement=1 to the query part of the endpoint and enter in the action section of the endpoint the agreement number of the device indead of the ID.
Show one
GET /contract-licenses/<id>
Create one
POST /contract-licenses/device/<id|internal_id|agreement_number>
To create a new contract lincese, use the WsContractLicense key in the body section. You can send the following key-value pairs within the body section:
- WsContractLicense[software_license_part_number]=021-08183
- WsContractLicense[number_of_licenses]=6
- WsContractLicense[start_date]=2022-04-15
- WsContractLicense[end_date]=
The key-value pairs "WsContractLicense[start_date]" and "WsContractLicense[end_date]" are optional.
Delete all by workspace
DELETE /contract-licenses
Be careful with this action. It deletes all contract licenses within the workspace.
Delete all by customer
DELETE /contract-licenses/customer/<id|internal_id>
Delete all by device
DELETE /contract-licenses/device/<id|internal_id|agreement_number>
Delete one
DELETE /contract-licenses/<id>
Activities
GET /activity/activities
Because of the big amount of activities, this API endpoint has per default pagination activated. The default pagination will show 300 entries per page. You can filter the activities by using the Activity key in the query parameter section after the question mark.
Reports
Licensing
Note: The API for the licensing report has default payloads to set:
- payload[month_id]: Defines the relevant month of the report. The month_id is a combination of the YEAR (e.g. 2021) and the MONTH (e.g. 01). For instance, a possible value for month_id would be payload[month_id]=202101, which would generate the report for January 2021.
- payload[compare_months]: This payload is not required. You can define comma-separated other months you would like to compare with the actual report. For instance, possible values for compare_months would be payload[compare_months]=202012 or payload[compare_months]=202012,202011,202010
- payload[with_itemized]=1 or 0
- payload[flat_structure]=1 or 0
- payload[existing]=1 or 0, if the value is set to 1, it will check if already an existing report with the same month_id exists, if yes, it will not regenerate a new report, but serve the existing one. If the value is set to 0, it will try to generate a new report, if the 5th of the next month is not exceeded.
SPLA usage report for reseller
With observation period for the full month (recommended)
GET /report/licensing/spla-usage-reseller?…&payload[month_id]=202007
With a date range
GET /report/licensing/spla-usage-reseller?…&payload[start_date]=2020-07-01&payload[end_date]=2020-07-31
Without observation period
GET /report/licensing/spla-usage-reseller?…&payload[without_high_water_mark]=1
Usage report for customer billing
With observation period for the full month (recommended)
GET /report/licensing/spla-usage-customer?…&payload[month_id]=202007
With a date range
GET /report/licensing/spla-usage-customer?…&payload[start_date]=2020-07-01&payload[end_date]=2020-07-31
Without observation period
GET /report/licensing/spla-usage-customer?…&payload[without_high_water_mark]=1
For a specific customer
GET /report/licensing/spla-usage-customer?…&payload[start_date]=2020-07-01&payload[end_date]=2020-07-31&payload[customer_ids]=<customer-id>
Response of the usage report
When you generate your usage report, it presents information grouped in the
following categories:
- summaryLicenses: The summaryLicenses category shows a summary of all calculated usage licenses. We recommend using the payload[flat_structure]=1 in the API request URL as a parameter to iterate easier through the results. Each item inside an object represents one license product.
- itemized: The itemized category lists all licenses in detail. The itemized category is only loaded, when the payload[with_itemized]=1 is added to the API request URL.
- customersServersSoftware
- missingUnitPrices: If licenses are calculated for license agreements where the purchase price is missing, you can find them under this category. Each item in an object presents the part number and the price category of a specific license. You must add the purchase price for each license or the license won’t be calculated for the usage reports. The purchase prices for each calculated license are required. The system uses the purchase prices to calculate break-even points informing which license is the most cost-effective.
Delete one
DELETE /report/licensing/<id>
Cloud
Cloud VM Cost Adviser
- payload[customer_id]: If the payload is set, then the report will only be generated for the defined customer. If the payload is not set, the report will be generated for all available customers.
-
payload[cloud_provider]: Set the specific cloud provider for who you want to generate the report. You can set multiple cloud providers comma separated. If the payload is not set, it will generated the report for all available cloud providers. Available values to set:
- 10_ms_azure: Microsoft Azure
- 20_amazon_web_services_aws: Amazon Web Services (AWS)
GET /report/cloud/cloud-vm-cost-adviser?…&payload[cloud_provider]=10_ms_azure&payload[customer_id]=10
Data Export
GET /report/data-export?..&payload[category]=<category>&payload[start_date]=2020-07-01&payload[end_date]=2020-07-31
The <category> parameter represents which category you want to export the data. You can enter one of the following categories:
- WsDatanceter
- WsCluster
- WsDevice
- WsInstalledSoftware-server
- WsUser
- WsInstalledSoftware-user
- WsCustomer
- WsAssignedDevice
- WsCustomerGroup
- WsScanAlert
- WsScanner