Overview

Openlane provides the ability to import controls from CSV files - this allows you to bring in controls that you may have already defined in other systems or spreadsheets, or as a method of pre-composing data

Importing Controls

Controls will generally fall into two buckets: those that are from a published framework or standard (ex: NIST 800-53), and custom controls. We recommend that you orient your compliance program to be based on an existing framework / standard even if you may have some custom controls outside of that. This way, you can add implementation details, objectives, evidence, etc., related to the controls from the published framework and receive the ongoing benefits of updates and changes we will publish as the upstream standard(s) are updated.

Framework Controls

Even if you are coming with controls from another system, it's best to clone them from our existing standard catalog rather than creating all of the controls as custom. To accomplish this, you'll need to ensure you have the fields outlined in the below table.

CSV Fields

Field Name	Description	Example / Notes	Required
StandardShortName	The short name of the standard.	Possible values: • SOC 2 • NIST CSF • NIST 800-53 • ISO 27001 • HIPAA • NIST 800-171 • GDPR • PCI DSS	✅ Yes
StandardVersion	Optional. Only required if there are multiple versions of the same standard (not applicable today).	e.g. 2017 - with revised points of focus 2022, 5.1.1 versions	❌ No
RefCode	Reference code or ID from the standard. Both the stored ref code and any known aliases will be matched.	Example for NIST 800-53: "refCode": "AC-17.3" "aliases": ["AC-17(03)", "AC-17(3)", "ac-17.03"]	✅ Yes
ControlImplementation	Implementation details of how the control is met.	Free text	✅ Yes
ControlObjective	The objective or intended outcome of the control.	Free Text	❌ No
ImplementationGuidance	Additional guidance or instructions for implementing the control.	e.g. frequency, responsible roles, procedures	❌ No
Comment	Additional context or commentary.	Internal notes, caveats, reviewer feedback, etc.	❌ No
Status	The current status of the control.	Common values include NOT_IMPLEMENTED, PREPARING, NEEDS_APPROVAL, APPROVED, See all values in our documentation.	❌ No
ReferenceID	Internal reference ID of the control object.	Useful for linking to external systems	❌ No
All control fields	All other fields on the control object are supported except for a few list-type fields.	Refer to documentation for the complete list.	❌ No

tip

Refer to our documentation for a list of all fields supported on controls. As of today, all fields should be supported. When putting fields that are lists in the csv, such as MappedCategories they need to be in as JSON, for example ["Security"]. If the field is JSON, such as ExampleEvidence you need to escape the quotes, for example: [{""documentationType"":""Other documentation"",""description"":""Evidence that the values have been communicated to employees during onboarding and annually thereafter""}]"

Example CSV Format

StandardShortName,RefCode,ControlInput.Status,ControlInput.ReferenceID,ControlImplementation,ImplementationGuidance,Comment
NIST 800-53,AC-1,NEEDS_APPROVAL,INT-0001,The organization has implemented technical and administrative controls to address this requirement. Automated tooling and manual oversight are combined to meet the control objectives. Access and configuration are reviewed regularly to maintain compliance.,The organization has implemented technical and administrative controls to address this requirement.,No exceptions are currently documented for this control. Further enhancements may be planned as the environment evolves.

The above will clone the AC-1 control from NIST 800-53, set the status of the control to NEEDS_APPROVAL and there reference id to INT-0001, add implementation guidance to what is provided by the standard. It will additionally create a control implementation and comment linked back to the created control.

note

The cases of the field matters. All field names must be in UpperCamelCase and any field directly on the control object must be prefixed with ControlInput. For example status would be ControlInput.Status

Upload Through Console

1. Login to console
2. Navigate to the controls table by clicking on Controls and then toggle to the table view.
3. Click the ... and select Upload From Standard
4. You should now have a dialog where you can either use the file selector or drag and drop your csv
5. Once you've selected your csv, click Upload. Depending on the number of controls this make take a little bit of time. If you have issues with timeouts, try breaking your csv into smaller chunks and uploading multiple times.
6. When it is complete the dialog will close and you should see a success message and the table should now be populated with your controls

Upload through the API

info

You'll need an API token to follow these steps. You can create an api token in console in developer settings

1. Using a GraphQL tool such as Apollo Explorer, you can send an API request:

    mutation CloneBulkCSVControl($input: Upload!) {
    cloneBulkCSVControl(input: $input) {
        controls {
        id
        refCode
        referenceFramework
        referenceFrameworkRevision
        description
        status
        subcontrols {
            edges {
            node {
                id
                refCode
                referenceFramework
                referenceFrameworkRevision
                description
                status
            }
            }
        }
        }
    }
    }

tip

See our Compliance collection in Apollo Studio for quick access to the query

1. Add your API key to the Authorization header as Bearer tola_ where your api token is tola_xxxx
2. Add the .csv file using Add files and set the key to input
3. Run the query, controls should be created + response returned such as:

  "data": {
    "cloneBulkCSVControl": {
      "controls": [
        {
          "id": "01K7321328TSZAND058QNNBK54",
          "refCode": "AC-1",
          "referenceFramework": "NIST 800-53",
          "referenceFrameworkRevision": "v0.0.1",

Import custom controls

CSV Fields

All other fields on the control object are supported. The RefCode is the only required field.

tip

Refer to our documentation for a list of all fields supported on controls. As of today, all fields should be supported. When putting fields that are lists in the csv, such as MappedCategories they need to be in as JSON, for example ["Security"]. If the field is JSON, such as ExampleEvidence you need to escape the quotes, for example: [{""documentationType"":""Other documentation"",""description"":""Evidence that the values have been communicated to employees during onboarding and annually thereafter""}]"

Example CSV Format

RefCode,Description,Category,AuditorReferenceID,MappedCategories
CO-07,Company has established core values (Code of Conduct) that are communicated to employees (and contractors) during onboarding and on an ongoing basis thereafter.,Organizational Governance and Structure,AU-07,["Security"]

The above will create a control with the RefCode CO-07, with an auditor reference ID AU-07.

note

The cases of the field matters - all field names must be in UpperCamelCase

Through Console

1. Login to console
2. Navigate to the controls table by clicking on Controls and then toggle to the table view
3. Click the ... and select Upload Custom Controls
4. You should now have a dialog where you can either use the file selector or drag and drop your csv
5. Once you've selected your csv, click Upload. Depending on the number of controls this make take a little bit of time
6. When it is complete the dialog will close and you should see a success message and the table should now be populated with your controls
7. Now that your custom controls are imported, you'll most likely want to associate them to a program as well. You can filter by Custom standard from the control table view:
8. Click View Results
9. Select the checkbox on the top of each page until you have selected all controls
10. Select Bulk Edit (count)
11. Choose the Program field and select your program
12. Click Save

Import Control Mappings

If you are importing custom controls, but want to map them to existing standard controls to show alignment, you can do so via CSV as well.

Prior to creating the mappings, you must ensure all the expected controls exist in your organization. For example, if you imported you custom controls, but are mapping them to SOC 2 controls, you must first add the SOC 2 controls to your organization. This can be done by adding them from the standards catalog or creating a SOC 2 program which will automatically add them to your organization.

CSV Fields

The CSV can contain any of the fields from the MappedControl object, again in the UpperCamelCaseformat. For example:

FromControlRefCodes,ToControlRefCodes,MappingType,Confidence,Source,Relation,
["CUSTOM::CO-07"],["SOC 2::CC1.1"],SUBSET,100,IMPORTED,Mapping between SOC2 controls and our custom controls,

1. Go to the same menu as when importing the custom controls, but instead click Upload Control Mappings
2. Select the mapping csv file
3. Click Upload
4. After successful upload, you should see the mappings on the Related Controls panel on the control view screens