Import controls

We built CSV import so you can bring in controls you have already defined in other systems or spreadsheets, or prepare data before loading it into Openlane. Upload the CSV you already have, map its columns to Openlane fields, and preview the result before anything is created.

Most organizations define their own organization controls, which describe how the business operates, and map framework controls such as SOC 2, ISO 27001, or NIST 800-53 to them. One organization control can then show coverage across several frameworks. Import your organization controls first, then import the mappings that link each one to the framework controls it satisfies.

How import works

Open the import directly with Import controls or Import control mappings. You can also get there from Controls: switch to the table view, click the ... menu, and select Upload Custom Controls or Upload Control Mappings.

Controls use the same upload, map, and review flow as every other import in Openlane. See Import data from CSV for a walkthrough of each step, including remapping values such as statuses your file spells differently.

Importing controls

Your organization controls are the controls your teams own, implement, and collect evidence against.

Ref Code is the only required field. Every other column is optional, and every other field on the control object is supported.

When you import from the console, Openlane records each control's source as imported, and your column names do not need to match ours. Columns such as Control ID, Control Number, or Reference map to Ref Code, so a spreadsheet with Control IDs and Control Description columns imports as it is. Through the API, headers must match the field names.

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.

Open Import controls and follow the import steps. Once your controls are in, add them to a program. Filter the control table by the Custom standard, then:

1. Click View Results
2. Select the checkbox on the top of each page until you have selected all controls
3. Select Bulk Edit (count)
4. Choose the Program field and select your program
5. Click Save

info

The createBulkCSVControl mutation accepts a CSV directly through the API, without the mapping step. Through the API, headers must match the control field names in UpperCamelCase, lists must be JSON (for example ["Security"]), and JSON fields must have their quotes escaped, for example [{""documentationType"":""Other documentation"",""description"":""Evidence that the values have been communicated to employees during onboarding and annually thereafter""}]". Download the example CSV from the field reference in the console to start from the expected headers.

Importing control mappings

Mappings link your organization controls to the framework controls they satisfy, so a single control can show coverage for every framework it supports.

Every control a mapping refers to has to exist in your organization before you import it. If you are mapping your organization controls to System and Organization Controls 2 (SOC 2), add the SOC 2 controls first, either from the standards catalog or by creating a SOC 2 program, which adds them for you.

The CSV can contain any of the fields from the MappedControl object. When you import from the console and leave the source unmapped, Openlane records it as imported. 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,

Open Import control mappings and follow the import steps, resolving any flagged values such as a MappingType your file spells differently. After the import, the mappings appear on the Linked Controls panel of each control.

tip

Refer to our documentation for a list of all relationship types supported.

Cloning framework controls

To bring a framework's controls into your organization with your own status, implementation details, or comments already filled in, clone them from the standards catalog with Upload From Standard. This upload does not use the mapping step, so your CSV must use the fields in the table below.

Framework control 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""}]"

Framework control CSV example

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 the reference ID to INT-0001, and 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 case of the field names 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

Uploading framework controls

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 may 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; the table should now be populated with your controls

API

info

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

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. You should see the controls created and a response returned such as:

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