Skip to content

Create/Edit a Policy

A policy holds the rules for data sharing by utilizing metadata from the underlying dataset. This dataset can be either a single dataset or an uber dataset that consolidates multiple datasets.

A policy is created by sending a POST request to /v2/policies with a valid JWT. The body is a multipart/form-data that contains 3 objects:

Key Type Description
PolicyRequest application/json Required. Contains connection information for your policy
image multipart/form-data Optional. Attach the file to be used as the image on the policy page
licenseFile multipart/form-data Optional. Attach the file used as the license file for the policy

PolicyRequest

All attributes are required unless otherwise specified

name

The name of this policy. This is a free text field and is visible to subscribers in the catalog.

datasourceId

The ID of the linked dataset.

protectionLevel

The level of encryption. Valid string values are:

  • "NONE"
  • "PASSWORD"
  • "AES"
  • "HOMOMORPHIC"

reviewer

Optional. The email address of the reviewer, who will approve this policy creation request.

approveSubscriber

Boolean. Whether new subscribers need to be approved or not.

subscriptionType

Optional. How often does the subscriber pay for your data subscription. This is only required if you are monetizing data. Valid values: - Monthly - Annual - One Time

currencyType

Optional. This is the currency that the subscribers will pay. We only support "dollar" for now and it's required when subscriptionFee is specified.

subscriptionFee

Optional. The subscription cost. This is only required if you are monetizing data.

description

Optional. A description of the policy. It will be visible to permissioned user in the catalog.

rules

Who can "see" your data and under what condition can each one of them "see" what data.

"rules":[
   {"shareWith":[""],
   "attributes":[
      {"path":["table name","column1"],"fee":0},
      {"path":["table name","column2"],"fee":0},
      {"path":["table name","column3"],"fee":0}],
   "conditions":[{"column":"","operator":"","value":""}]}]

Here is an example rules section. This rule allows anyone in the ComplianceTeam to receive 3 columns "Transactions", "Category", "Amount" from the "creditcard_transactions" table where "CardType" is "Credit":

  "rules":[
    {"shareWith":["ComplianceTeam"],
        "attributes":[
            {"path":["creditcard_transactions","Transactions"],"fee":0},
            {"path":["creditcard_transactions","Category"],"fee":0},
            {"path":["creditcard_transactions","Amount"],"fee":0}],
        "conditions":[{"column":"CardType","operator":"EQUAL","value":"Credit"}]}]
  }

dataAvailableTime

Optional. The date and time of when data will be available. This object contains the following variables:

  • publishTime: Defines when data will be published, on what day and at what time. This is required when "updateFrequency" is specified.

    • time: 24 hour clock system in the format of hh:mm±hh:mm. Please refer to this ISO 8601 standard for more information
    • day: see table below

  • expirationTime: Defines when data rights will be revoked. If updateFrequency is specified, use a combination of "time" and "day". Please refer to the table below. If updateFrequency is not specified, the expirationTinme will be subscriber's subscription time + number of "days" + number of hours specified in the "time" field.

    • time: 24 hour clock system in the format of hh:mm±hh:mm. Please refer to this ISO 8601 standard for more information
    • day: see table below
    updateFrequency valid values for "day"
    Daily must be 0
    Weekly a number between 1 and 7. (the number of days in a week, from Monday to Sunday)
    Quarterly a number between 1 and 93. (the number of days in a quarter, assuming 31 days per month)
    Monthly a number between 1 and 31. (the number of days in a month)
    Yearly a number between 1 and 365. (the number of days in a year)

Example 1: data will be published weekly on Monday/1st day of the week at 12:50UTC and data rights will be revoked on Sunday/7th day of the week at 15:50 UTC+5 hours offset/10:50UTC

dataAvailableTime: {
    publishTime : {
        time : “12:50Z”,
        day: 1
    },
    expirationTime: {
        time : “15:50+05:00”,
        day: 7
    }   
}

Example 2: Data does not have a publish schedule (no updateFrequency and no publishTime). However data rights will be revoked 7 days and 12 hours after subscriber's subscription time:

dataAvailableTime: {
    publishTime : {
    },
    expirationTime: {
        time : “12:00+00:00”,
        day: 7
    }   
}

updateFrequency

Optional. Data update frequency. One of the following enumerated values:

- Daily
- Weekly
- Monthly
- Quarterly
- Yearly

validPeriod

An optional boolean value that indicates whether the data is available for a specific period of time. By default, this flag is set to 'false.' When set to 'true,' the validPeriodTime and validPeriodUnit must be specified.

Valid values for validPeriodTime are: - Hours - Days - Months - Years

validPeriodUnit is an integer field represnets the value of the time period.

image

Optional. A MultipartFile field. The image/logo that is displayed in the Smart Market. If not specified, we will use policyName here instead.

licenseFile

Optional. A MultipartFile field. This is your data consumption/license agreement as an attachment.

Example

Here is an example of the request you would send to create a policy.

Using a GET request to /v1/organizations//groups you can find the Id of groups you wish to share your policies with. Organization IDs can be found under user profile in the One Creation GUI. 

{
    "datasourceId": "",
    "name": "",
    "protectionLevel": "NONE",
    "reviewer": "",
    "approveSubscriber": false,
    "subscriptionFee": 0,
    "currencyType":"dollar",
    "subscriptionType":"",
    "updateFrequency": "",
    "isRealTime":true,
    "validPeriod":false,
    "validPeriodTime":"",
    "validPeriodUnit":0,
    "timezone":"America/New_York",
    "description": "",
     "dataAvailableTime": {
        "publishTime": {
        "time": "+00:00",
        "day": 0
        }
    },
    "rules":[
    {"shareWith":[""],
        "attributes":[
            {"path":["creditcard_transactions","Transactions"],"fee":0},
            {"path":["creditcard_transactions","Category"],"fee":0},
            {"path":["creditcard_transactions","Amount"],"fee":0}],
        "conditions":[{"column":"Type","operator":"EQUAL","value":"Credit"}]}]
  }

Response

After the successful creation of a policy, you will receive a success response with status code 201.

If the creation of the policy fails, you will receive a 4xx or 5xx error code with details in the response body. Please refer to this REST API Tutorial for the full list of all HTTP status codes.

Editing a Policy

After the app is created, you may wish to edit the app. This can be accomplished by sending a POST request to /v2/policies/{policyId}/edit with a valid JWT.

You will need the policyId of the app you wish to edit.

After a successful edit of the app you will receive a sucess response with status code 200. If the update has failed, you will receive a 4xx or 5xx error code with the details in the response body. Please refer to this REST API Tutorial for further guidance on HTTP status codes.

Next Step

If a reviewer is specified, as soon as the policy is created, the reviewer receives a notification to approve the policy creation request. The policy will in be pending status until it is approved.

If a reviewer is not specified, as soon as the policy is created successfully, its status is "Live". The "Live" dataset and policy are visible to all authorized data recipients.

Last update: May 18, 2023