Back to SamaKnow landing

Configuration

What do you need?

First, you need to specify two things:

  1. The Sama Project ID
  2. API Key or Sama credentials

🚧

Warning

  • Your project manager must provide the information listed above.
  • The following instructions also assume that your Sama Project manager has already configured all the neccessary Sama Project inputs and outputs.

Step 1: Set the current working directory

Create a new folder and set the current working directory to it

$ mkdir my_sama_project
$ cd my_sama_project

Step 2: init command

Run the sama init command

$ sama init
? Project ID: YOUR_SAMA_PROJECT_ID
? Email: (Any email to get notified when task creation is done)
? How would you like to authenticate the Sama CLI? (Choose one of the following)
       Option 1: Log in with Sama username and password - Your web browser will open and ask you to log in with your Sama credentials. Once logged in, copy and paste the Login token into the CLI.
       Option 2: Provide API Key - YOUR_SAMA_API_KEY

The above data will be saved into .sama.yaml (and .sama.creds.yaml if you're authenticating with Sama credentials) in your current working directory.

Step 3: Create the mapping JSON

You'll then be prompted to create the mapping JSON which contains your Sama Project inputs and maps it to the values generated by the CLI. The CLI will attempt to auto-generate the mapping JSON by looking at the required inputs set up in your Sama Project. See Configuring the mapping json below for more info.

? No mapping json found in project. Would you like to auto-generate it? Yes
{
  "name": "{{ .BaseName }}",
  "url": "{{ .URL }}",
  "client batch id": "{{ .ClientBatchID }}",
  "group id": "{{ .GroupID }}",
  "file size": "{{ .FileSizeBytes }}"
}

The above example has a Sama Project already set up with inputs "name"(string), "url"(URL), "client batch id"(string), "group id"(string), and "file size"(string). The mapping JSON will be saved into .mapping.json.gotmpl in your current working directory.

Advanced configuration of the mapping JSON

The mapping JSON, mapping.json.gotmpl, contains your Sama Project inputs and values that will be sent during task creation. The values that you see in {{ }} are special variables used by the CLI and are replaced during task creation. The list of special variables is:

PropertyValue
{{.BaseName}}Will be replaced by the asset's name, e.g. image001.png.
{{.AssetFolderName}}Will be replaced by the name of the containing folder. For example, the folder in s3 contains the asset.
{{.URL}}Will be replaced by the asset's URL path in Sama's S3, e.g. https://sama-client-assets.s3.amazonaws.com/123/assets_batch001/image001.png
{{.ClientBatchID}}Will be replaced by the string specified with the --client-batch-id flag
{{.GroupID}}Will be replaced by a unique groupID when using the --group-size flag
{{.FileSizeBytes}}Will be replaced by the asset's file size

What happens when you call sama init?

When you call sama init, the CLI will do its best to automatically use the special variables depending on your Sama Project's inputs.

  • If you have an input called "name", "asset name", or "file name", the CLI will automatically insert "{{ .BaseName }}" as its value.
  • If you have an input type of "URL", the CLI will automatically insert "{{ .URL }}" as its value.
  • If you have an input type that is marked as "Client Batch ID", the CLI will automatically insert "{{ .ClientBatchID }}" as its value.
  • If you have an input type that is marked as "Task Group ID", the CLI will automatically insert "{{ .GroupID }}" as its value.
  • If you have an input called "size", "asset size", or "file size", the CLI will automatically insert "{{ .FileSizeBytes}}" as its value.

If needed, modify mapping.json.gotmpl so that the proper data is sent during task creation. Examples of the mapping JSON are given below.