Reports-v1 1.0.0

Reports

1. Authenticate

Prerequisites

  1. You should have registered in our developer portal. Check this link about how to register an Account.
  2. You should request access to the playground, sandbox and production environment using our Support page. Here is the link to support page to request access to our environments.
  3. You should have an App created in your account to get the client id and client secret. Check this link about how to create an App.

Note : The time data attribute on APIs follows a 24-hour clock starting at 00:00 and ending at 23:59.

 

Authentication

The bearer token obtained after successful authentication should be passed as credential when calling this API for authentication. Check the Access Token API link for instructions on how to generate your bearer token.

 

 

Read the Get Started documentation if you are unaware of your client credentials.

 

2. Get Information

Get Account Information

Master account Id and account Id need to be passed in the header for this API call. This is needed to indicate your legal entity.
Refer to the Accounts API for instructions on how to retrieve your account information. You may skip this step if you already know your master account Id and account Id.

3. Retrieve Reports

How to download a report.

  1. Use the GET reports/request endpoint to retrieve the list of CI's (configuration items).
  2. Using the POST reports endpoints with the list of CI's in the request body to retrieve the list of reports.
  3. Optional use the GET reports/{id} endpoint to get more details about a report.
  4. Download the report by using the GET reports/{id}/download.

Request CI Information

The method can be used to request CI's that are needed to retrieve reports.

 Method GET
End point /v1/reports/request
Headers authorization, master-account-id, account-id
Query Parameters n/a
Body n/a

 

Sample Curl Request

curl --location --request GET 'https://api.digitalrealty.com/v1/reports/request' \
--header 'Master-Account-Id: <your_master_account_id>' \
--header 'Account-Id: <your_account_id>' \
--header 'Authorization: Bearer <your_access_token>'

 

Headers

Field Name Mandatory Type Description
Authorization true string Token-based authentication.
Master-Account-Id true string Customer master account identifier.
Account-Id true string Customer account identifier.

 

Query Parameters

n/a

Body

n/a

Sample JSON Response

{
    "ci": [
        "8b077e841bb2c5d48b000e55cc4bcb",
        "f64eca711b29c9104c384047bc4bcb"
    ]
}

 

Payload Description

Field Name Type Description
ci array(string) List of configuration items needed for the reports

Retrieve Reports List

The method can be used to retrieve reports for one or more CI's

 Method POST
End point /v1/reports
Headers Authorization, Master-Account-Id, Account-Id, Content-Type
Query Parameters site, location, reportType, reportName, reportStartDate, reportEndDate, size, page
Body ci

 

Sample Curl Request

curl --location --request POST 'https://api.digitalrealty.com/v1/reports' \
--header 'Master-Account-Id: <your_master_account_id>' \
--header 'Account-Id: <your_account_id>' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "ci": [
        "8b077e841bb2c5d48b000e55cc4bcb",
        "f64eca711b29c9104c384047bc4bcb"
    ]
}'

 

Headers

Field Name Mandatory Type Description
Authorization true string Token-based authentication.
Master-Account-Id true string Customer master account identifier.
Account-Id true string Customer account identifier.
Content-Type true string Indicates the request body format.

value: [application/json]

 

Query Parameters

Field Name Mandatory Type Description
site false string(6) 6 digit alphanumeric code that uniquely identifies each data center.
location false string(40) Data center space (suite, cage, rack) occupied by customer at the site.
reportType true string(enum) Determines the type of the report.

values: [Security, DCIM]
reportName false string(160) Name of report.
reportStartDate false string($date-time) Date from which data is pulled.

format: [yyyy-MM-dd]
reportEndDate false string($date-time) Date to which data is pulled.

format: [yyyy-MM-dd]
size false integer The maximum number of search results to return.

Default value: 25
page false integer The page number of the returning search results.

Default value: 0

 

Body

Field Name Mandatory Type Description
ci true array(string) List of configuration items needed for the reports

 

Sample JSON Response

{
    "content": [
        {
            "id": "CUS0123456",
            "site": "DFW010",
            "location": "Room 01",
            "type": "Security",
            "name": "ABC_Company_DFW010_Room_01_Cardholder_Sep_2022.csv",
            "executionDate": "2022-09-27 23:42:12",
            "startDate": "2022-07-30 17:00:00",
            "endDate": "2022-08-31 17:00:00"
        }
    ],
    "pageable": {
        "last": true,
        "totalPages": 1,
        "totalElements": 1,
        "size": 25,
        "number": 0,
        "first": true,
        "numberOfElements": 1,
        "empty": false
    }
}

 

Payload Description

Field Name Type Description
id string(20) Identifier for the report.
site string(6) 6 digit alphanumeric code that uniquely identifies each data center.
location string(40) Data center space (suite, cage, rack) occupied by customer at the site.
type string(enum) Determines the type of the report.

values: [Security, DCIM]
name string(160) Name of report.
executionDate string($date-time) Date when the report was run.

format: [yyyy-MM-dd HH:mm:ss] timezone: [GMT]
startDate string($date-time) Date from which data is pulled.

format: [yyyy-MM-dd HH:mm:ss] timezone: [GMT]
endDate string($date-time) Date to which data is pulled.

format: [yyyy-MM-dd HH:mm:ss] timezone: [GMT]

Retrieve Report Details

The method can be used to retrieve the details of a report.

 Method GET
End point /v1/reports/{id}
Headers Authorization, Master-Account-Id, Account-Id
Query Parameters n/a
Body n/a

 

Sample Curl Request

curl --location --request GET 'https://api.digitalrealty.com/v1/reports/<report_number' \
--header 'Master-Account-Id: <your_master_account_id>' \
--header 'Account-Id: <your_account_id>' \
--header 'Authorization: Bearer <your_access_token>'

 

Headers

Field Name Mandatory Type Description
Authorization true string Token-based authentication.
Master-Account-Id true string Customer master account identifier.
Account-Id true string Customer account identifier.

 

Query Parameters

n/a

Body

n/a

 

Sample JSON Response

{
    "id": "CUS0123456",
    "site": "DFW010",
    "location": "Room 01",
    "type": "Security",
    "name": "ABC_Company_DFW010_Room_01_Cardholder_Sep_2022.csv",
    "executionDate": "2022-09-27 23:42:12",
    "startDate": "2022-07-30 17:00:00",
    "endDate": "2022-08-31 17:00:00"
}

 

Payload Description

Field Name Type Description
id string(20) Identifier for the report.
site string(6) 6 digit alphanumeric code that uniquely identifies each data center.
location string(40) Data center space (suite, cage, rack) occupied by customer at the site.
type string(enum) Determines the type of the report.

values: [Security, DCIM]
name string(160) Name of report.
executionDate string($date-time) Date when the report was run.

format: [yyyy-MM-dd HH:mm:ss] timezone: [GMT]
startDate string($date-time) Date from which data is pulled.

format: [yyyy-MM-dd HH:mm:ss] timezone: [GMT]
endDate string($date-time) Date to which data is pulled.

format: [yyyy-MM-dd HH:mm:ss] timezone: [GMT]

Download a Report

The method that can be used to download the report.

 Method GET
End point /v1/reports/{id}/download
Headers Authorization, Master-Account-Id, Account-Id
Query Parameters n/a
Body n/a

 

Sample Curl Request

curl --location --request GET 'https://api.digitalrealty.com/v1/reports/<report_number>/download' \
--header 'Master-Account-Id: <your_master_account_id>' \
--header 'Account-Id: <your_account_id>' \
--header 'Authorization: Bearer <your_access_token>'

 

Headers

Field Name Mandatory Type Description
Authorization true string Token-based authentication.
Master-Account-Id true string Customer master account identifier.
Account-Id true string Customer account identifier.

 

Query Parameters

n/a

Body

n/a

Sample JSON Response

string($binary)

 

Payload Description

Field Name Type Description
file string($binary) File content.

4. Retrieve Workorders

How to download a workorder file.

  1. Use the GET workorder/request endpoint to retrieve the list of CI's (configuration items).
  2. Using the POST workorder endpoints with the list of CI's in the request body to retrieve the list of workorders.
  3. Optional use the GET workorders/{id} endpoint to get more details about a workorder file.
  4. Download the relevant attachments by using the attachments API.

Request CI Information

The method can be used to request CI's that are needed to retrieve workorders.

 Method GET
End point /v1/workorders/request
Headers authorization, master-account-id, account-id
Query Parameters n/a
Body n/a

 

Sample Curl Request

curl --location --request GET 'https://api.digitalrealty.com/v1/workorders/request' \
--header 'Master-Account-Id: <your_master_account_id>' \
--header 'Account-Id: <your_account_id>' \
--header 'Authorization: Bearer <your_access_token>'

 

Headers

Field Name Mandatory Type Description
Authorization true string Token-based authentication.
Master-Account-Id true string Customer master account identifier.
Account-Id true string Customer account identifier.

 

Query Parameters

n/a

Body

n/a

Sample JSON Response

{
    "completed": [
        "fd1814dc1b7ac59471b884415b4bcb",
        "b6077e841bb2c5d48b000e55cc4bcb"
    ],
    "scheduled": [
        "fd1814dc1b7ac59471b884415b4bcb",
        "b6077e841bb2c5d48b000e55cc4bcb"
    ]
}

 

Payload Description

Field Name Type Description
completed array(string) List of configuration items needed for the completed workorders.
scheduled array(string) List of configuration items needed for the scheduled workorders.

Retrieve Workorder List

The method can be used to retrieve workorders for one or more CI's

 Method POST
End point /v1/workorders
Headers Authorization, Master-Account-Id, Account-Id, Content-Type
Query Parameters site, location, status, activityType, shortDescription, startDate, endDate, size, page
Body completed, scheduled

 

Sample Curl Request

curl --location --request POST 'https://api.digitalrealty.com/v1/workorders' \
--header 'Master-Account-Id: <your_master_account_id>' \
--header 'Account-Id: <your_account_id>' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "completed": [
        "fd1814dc1b7ac59471b884415b4bcb",
        "b6077e841bb2c5d48b000e55cc4bcb"
    ],
    "scheduled": [
        "fd1814dc1b7ac59471b884415b4bcb",
        "b6077e841bb2c5d48b000e55cc4bcb"
    ]
}'

 

Headers

Field Name Mandatory Type Description
Authorization true string Token-based authentication.
Master-Account-Id true string Customer master account identifier.
Account-Id true string Customer account identifier.
Content-Type true string Indicates the request body format.

value: [application/json]

 

Query Parameters

Field Name Mandatory Type Description
site false string(6) 6 digit alphanumeric code that uniquely identifies each data center.
location false string(40) Data center space (suite, cage, rack) occupied by customer at the site.
status false string(enum) Defines the current status of the workorder.

Values: [completed, scheduled]
activityType false string(40) Defines the kind of system worked on.
shortDescription false string(40) Short description of the work.
startDate false string($date) Date from which data is pulled.

format: [yyyy-MM-dd]
endDate false string($date) Date to which data is pulled.

format: [yyyy-MM-dd]
size false integer The maximum number of search results to return.

Default value: 25
page false integer The page number of the returning search results.

Default value: 0

 

Body

Field Name Mandatory Type Description
completed true array(string) List of configuration items needed for the completed workorders.
scheduled true array(string) List of configuration items needed for the scheduled workorders.

 

Sample JSON Response

{
    "content": [
        {
            "id": "WO1234567",
            "shortDescription": "2022 PPM Fire System Monthly Servicing (Nov)",
            "site": "DFW010",
            "location": "Room 01",
            "startDate": "2022-11-01 00:00:00",
            "endDate": "2022-12-01 00:00:00",
            "status": "Scheduled",
            "activityType": "Fire Systems"
        }
    ],
    "pageable": {
        "last": true,
        "totalPages": 1,
        "totalElements": 1,
        "size": 25,
        "number": 0,
        "first": true,
        "numberOfElements": 1,
        "empty": false
    }
}

 

Payload Description

Field Name Type Description
id string(20) Identifier for the report.
shortDescription string(40) Short description of the work.
site string(6) 6 digit alphanumeric code that uniquely identifies each data center.
location string(40) Data center space (suite, cage, rack) occupied by customer at the site.
status string(enum) Defines the current status of the workorder.

Values: [completed, scheduled]
activityType string(40) Defines the kind of system worked on.
startDate string($date-time) Date from which data is pulled.

format: [yyyy-MM-dd HH:mm:ss] timezone: [GMT]
endDate string($date-time) Date to which data is pulled.

format: [yyyy-MM-dd HH:mm:ss] timezone: [GMT]

Retrieve Workorder Details

The method can be used to retrieve the details of a workorder.

 Method GET
End point /v1/workorder/{id}
Headers Authorization, Master-Account-Id, Account-Id
Query Parameters n/a
Body n/a

 

Sample Curl Request

curl --location --request GET 'https://api.digitalrealty.com/v1/workorder/<workorder_number' \
--header 'Master-Account-Id: <your_master_account_id>' \
--header 'Account-Id: <your_account_id>' \
--header 'Authorization: Bearer <your_access_token>'

 

Headers

Field Name Mandatory Type Description
Authorization true string Token-based authentication.
Master-Account-Id true string Customer master account identifier.
Account-Id true string Customer account identifier.

 

Query Parameters

n/a

Body

n/a

 

Sample JSON Response

{
    "id": "WO1234567",
    "shortDescription": "2022 PPM Fire System Monthly Servicing (Nov)",
    "site": "DFW010",
    "location": "Room 01",
    "startDate": "2022-11-01 00:00:00",
    "endDate": "2022-12-01 00:00:00",
    "status": "Scheduled",
    "approvalStatus": "Approved",
    "activityType": "Fire Systems",
    "activitySubType": "Fire System Panel",
    "activityCategory": "Facilities Request",
    "serviceType": "Planned Maintenance",
    "riskLevel": "High",
    "highLevelSummary": "Please refer to the attached MOP for details",
    "methodOfProcedure": null,
    "attachments": []
}

 

Payload Description

Field Name Type Description
id string(20) Identifier for the workorder.
shortDescription string(40) Short description of the work.
site string(6) 6 digit alphanumeric code that uniquely identifies each data center.
location string(40) Data center space (suite, cage, rack) occupied by customer at the site.
startDate string($date-time) Date from which data is pulled.

format: [yyyy-MM-dd HH:mm:ss] timezone: [GMT]
endDate string($date-time) Date to which data is pulled.

format: [yyyy-MM-dd HH:mm:ss] timezone: [GMT]
status string(enum) Defines the current status of the workorder.

Values: [completed, scheduled]
approvalStatus string(40) Indicated if the workorder is approved.
activityType string(40) Defines the kind of system is worked on.
activitySubType string(40) Defines a specific or granular component/equipment in the system.
activityCategory string(40) Defines the category of the work performed.
serviceType string(40) Indicates routine planned work.
riskLevel string(enum) Defines the potential impact to the customer.

Values: [Critical, High, Low]
highLevelSummary string(200) This is a high level description of the work to be performed.
methodOfProcedure string  
attachments array Array of attachments.

Response Codes


Please check the Response Codes overview in case of any issues.


Need Help?

Have not found what you are looking for, please do not hesitate to reach out to us!

FAQs
Contact Us
globe