Skip to main content

Import an Artifact

This guide will show you how to import a custom artifact into your organization. Why might you want to import an artifact? Here are some possible scenarios:

  • You want to connect resources in Massdriver to resources outside of Massdriver
  • You want to customize the artifact data for a specific use case

Prerequisites​

To import an artifact, you need a schema (artifact definition). You can either create a custom artifact definition or use an official Massdriver artifact definition.

We'll also need a custom artifact that meets that schema, populated with actual values. Here's an example:

schema.json
{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "title": "AWS VPC",
  "description": "My custom AWS VPC",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "title": "Artifact Data",
      "type": "object",
      "required": [
        "infrastructure"
      ],
      "properties": {
        "infrastructure": {
          "title": "Infrastructure configuration",
          "required": [
            "arn",
            "cidr",
          ],
          "type": "object",
          "properties": {
            "arn": {
              "type": "string",
              "title": "AWS ARN",
              "description": "Amazon Resource Name",
            }
            "cidr": {
                "type" : "string",
                "title": "CIDR",
                "description": "CIDR block for the VPC"
            }
          }
        }
      }
    },
    "specs": {
      "title": "Artifact Specs",
      "type": "object",
      "properties": {
        "aws": {
          "region": {
            "type": "string",
            "title": "Region",
            "description": "AWS Region to provision in.",
          }
        }
      }
    }
  }
}
artifact.json
{
  "data": {
    "infrastructure": {
      "arn": "arn:aws:ec2:us-west-2:123456789012:vpc/vpc-1234567890abcdef0",
      "cidr": "10.0.0.0/16"
    }
  },
  "specs": {
    "aws": {
      "region": "us-west-2"
    }
  }
}

CLI​

note

If you haven't already, be sure to install the CLI.

Once you have a schema and the custom artifact, you can import the artifact using the following command:

mass artifact import -n my-artifact-name -t mymdorg/myartifactdef -f /path/to/artifact.json

You'll then see the following output:

Output
Creating artifact my-artifact-name of type mymdorg/myartifactdef...
Artifact my-artifact-name created! (Artifact ID: 12345678-1234-1234-1234-123456789012)

You can now view the artifact in the Massdriver UI.

API​

To import an artifact using the API, you can do so using GraphiQL, GraphQL, Fetch, or a cURL request.

GraphiQL​

You can access our GraphiQL interface here.

createArtifact.gql
mutation importVpc($orgId: ID!) {
  createArtifact(
    data: "{\"infrastructure\":{\"arn\":\"arn:aws:ec2:us-west-2:123456789012:vpc/vpc-1234567890abcdef0\",\"cidr\":\"10.0.0.0/16\"}}"
    name: "my-artifact-name"
    organizationId: $orgId
    specs: "{\"aws\":{\"region\":\"us-west-2\"}}"
    type: "mymdorg/myartifactdef"
  ){
    result{id}
    messages{message}
    successful
  }
}
query variables
{
  "orgId": "12345678-1234-1234-1234-123456789012"
}

GraphQL-Request​

createArtifact.js
import { GraphQLClient } from 'graphql-request'

const client = new GraphQLClient('https://api.massdriver.cloud/api/graphiql', {
  headers: {
    Authorization: 'Bearer YOUR_AUTH_TOKEN',
  },
});


function setItem() {
  return client.request(`
    {
      createArtifact(
        data: "{\"infrastructure\":{\"arn\":\"arn:aws:ec2:us-west-2:123456789012:vpc/vpc-1234567890abcdef0\",\"cidr\":\"10.0.0.0/16\"}}"
        name: "my-artifact-name"
        organizationId: $orgId
        specs: "{\"aws\":{\"region\":\"us-west-2\"}}"
        type: "mymdorg/myartifactdef"
      ){
        result{id}
        messages{message}
        successful
      }
    }
  `)
}

Fetch​

createArtifact.js
require('es6-promise').polyfill()
require('isomorphic-fetch')
      
function setItem() { 
  return fetch('https://api.massdriver.cloud/api/graphiql', {
    method: 'post',
    headers: {
      'Content-Type': 'application/json',
    //'Authorization': 'Bearer YOUR_AUTH_TOKEN'
    },
    body: '{"query":"mutationimportVpc($orgId:ID!){createArtifact(data:\"{\\\"infrastructure\\\":{\\\"arn\\\":\\\"arn:aws:ec2:us-west-2:123456789012:vpc/vpc-1234567890abcdef0\\\",\\\"cidr\\\":\\\"10.0.0.0/16\\\"}}\"name:\"my-artifact-name\"organizationId:$orgIdspecs:\"{\\\"aws\\\":{\\\"region\\\":\\\"us-west-2\\\"}}\"type:\"mymdorg/myartifactdef\"){result{id}messages{message}successful}}"}', 
  }) 
}

CURL​

cURL
curl 'https://api.massdriver.cloud/api/graphiql'  
  -H 'Authorization: Bearer YOUR_AUTH_TOKEN'  
  -d '{"query":"mutationimportVpc($orgId:ID!){createArtifact(data:\"{\\\"infrastructure\\\":{\\\"arn\\\":\\\"arn:aws:ec2:us-west-2:123456789012:vpc/vpc-1234567890abcdef0\\\",\\\"cidr\\\":\\\"10.0.0.0/16\\\"}}\"name:\"my-artifact-name\"organizationId:$orgIdspecs:\"{\\\"aws\\\":{\\\"region\\\":\\\"us-west-2\\\"}}\"type:\"mymdorg/myartifactdef\"){result{id}messages{message}successful}}"}'