How to Create an Organizational Chart with Separate Hierarchies by Using Amazon Cloud Directory

Amazon Cloud Directory enables you to create directories for a variety of use cases, such as organizational charts, course catalogs, and device registries. Cloud Directory offers you the flexibility to create directories with hierarchies that span multiple dimensions. For example, you can create an organizational chart that you can navigate through separate hierarchies for reporting structure, location, and cost center.

In this blog post, I show how to use Cloud Directory APIs to create an organizational chart with two separate hierarchies in a single directory. I also show how to navigate the hierarchies and retrieve data. I use the Java SDK for all the sample code in this post, but you can use other language SDKs or the AWS CLI.

Define a schema

The first step in using Cloud Directory is to define a schema, which describes the data that will be stored in the directory that you will create later in this post. In this example, I define the schema by providing a JSON document. The schema has two facets: Employee and Group. I constrain the attributes within these facets by using various rules provided by Cloud Directory. For example, I specify that the Name attribute is of type STRING and must have a minimum length of 3 characters and maximum length of 100 characters. Similarly, I specify that the Status attribute is of type STRING and the value of this attribute must have one of the following three values: ACTIVE, INACTIVE, or TERMINATED. Having Cloud Directory handle these constraints means that I do not need to handle the validation of these constraints in my code, and it also lets multiple applications share the data in my directory without violating these constraints.

I also specify that the objectType of Employee is a LEAF_NODE. Therefore, employee objects cannot have any children, but can have multiple parents. The objectType of Group is NODE, which means group objects can have children, but they can only have one parent object. In the next section, I show you how to create a directory with this schema by using some sample Java code. Save the following JSON document to a file and provide the path to the file in the code for creating the schema in the next section.

{
  "facets" : {
    "Employee" : {
      "facetAttributes" : {
        "Name" : {
          "attributeDefinition" : {
            "attributeType" : "STRING",
            "isImmutable" : false,
            "attributeRules" : {
              "NameLengthRule" : {
                "parameters" : {
                  "min" : "3",
                  "max" : "100"
                },
                "ruleType": "STRING_LENGTH"
              }
            }
          },
          "requiredBehavior" : "REQUIRED_ALWAYS"
        },
        "EmailAddress" : {
          "attributeDefinition" : {
            "attributeType" : "STRING",
            "isImmutable" : true,
            "attributeRules" : {
              "NameLengthRule" : {
                "parameters" : {
                  "min" : "3",
                  "max" : "100"
                },
                "ruleType": "STRING_LENGTH"
              }
            }
          },
          "requiredBehavior" : "REQUIRED_ALWAYS"
        },
        "Status" : {
          "attributeDefinition" : {
            "attributeType" : "STRING",
            "isImmutable" : true,
            "attributeRules" : {
              "rule1" : {
                "parameters" : {
                  "allowedValues" : "ACTIVE, INACTIVE, TERMINATED"
                },
                "ruleType": "STRING_FROM_SET"
              }
            }
          },
          "requiredBehavior" : "REQUIRED_ALWAYS"
        }
      },
      "objectType" : "LEAF_NODE"
    },
    "Group" : {
      "facetAttributes" : {
        "Name" : {
          "attributeDefinition" : {
            "attributeType" : "STRING",
            "isImmutable" : true
          },
          "requiredBehavior" : "REQUIRED_ALWAYS"
        }
      },
      "objectType" : "NODE"
    }
  }
}

Create and publish the schema

Similar to other AWS services, I have to create the client for Cloud Directory to call the service APIs. To create a client, I use the following Java code.

    AWSCredentialsProvider credentials = null;
    try {
        credentials = new ProfileCredentialsProvider("default");
    } catch (Exception e) {
        throw new AmazonClientException(
            "Cannot load the credentials from the credential profiles file. " +
            "Please make sure that your credentials file is at the correct " +
            "location, and is in valid format.",
            e);
    }
    AmazonCloudDirectory client = AmazonCloudDirectoryClientBuilder.standard()
            .withRegion(Regions.US_EAST_1)
            .withCredentials(credentials)
            .build(); 

Now, I am ready to create the schema that I defined in the JSON file earlier in the post. When I create the schema, it is in the Development state. A schema in Cloud Directory can be in the Development, Published, or Applied state. When the schema is in the Development state, I can make more changes to the schema. In this case, however, I don’t want to make additional changes. Therefore, I will just publish the schema, which makes it available for creating directories (you cannot modify a schema in the Published state). I discuss the Applied state for schemas in the next section. In the following code, change the jsonFilePath variable to the file location where you saved the JSON schema in the previous step.

    //Read the JSON schema content from the file. 
    String jsonFilePath = <Provide the location of the json schema file here>;
    String schemaDocument;
    try
    {
        schemaDocument = new String(Files.readAllBytes(Paths.get(jsonFilePath)));
    }
    catch(IOException e)
    {
        throw new RuntimeException(e);
    }
    
    //Create an empty schema with a schema name. The schema name needs to be unique
    //within an AWS account.    
    CreateSchemaRequest createSchemaRequest = new CreateSchemaRequest()
        .withName("EmployeeSchema");
    String developmentSchemaArn =  client.createSchema(createSchemaRequest).getSchemaArn();    
    
    //Load the previously defined JSON into the empty schema that was just created
    PutSchemaFromJsonRequest putSchemaRequest = new PutSchemaFromJsonRequest()
           .withDocument(schemaDocument)
           .withSchemaArn(developmentSchemaArn);
    PutSchemaFromJsonResult putSchemaResult =  client.putSchemaFromJson(putSchemaRequest);

    //No more changes needed for schema so publish the schema
    PublishSchemaRequest publishSchemaRequest = new PublishSchemaRequest()
        .withDevelopmentSchemaArn(developmentSchemaArn)
        .withVersion("1.0");
    String publishedSchemaArn =  client.publishSchema(publishSchemaRequest).getPublishedSchemaArn();

Create a directory by using the published schema

I am now ready to create a directory by using the schema I just published. When I create a directory, Cloud Directory copies the published schema to the newly created directory. The schema copied to this directory is in the Applied state, which means if I had a scenario in which a schema attached to a particular directory needed to be changed, I could make changes to the schema that is applied to that specific directory.

The following code creates the directory and receives the Applied schema ARN and directory ARN. This Applied schema ARN is useful if I need to make changes to the schema applied to this directory. The directory ARN will be used in all subsequent operations associated with the directory. Cloud Directory will use the directory ARN to identify the directory associated with incoming requests because a single customer can create multiple directories.

    //Create a directory using the published schema. Specify a directory name, which must be unique within an account.
    CreateDirectoryRequest createDirectoryRequest = new CreateDirectoryRequest()
        .withName("EmployeeDirectory")
        .withSchemaArn(publishedSchemaArn);
    CreateDirectoryResult createDirectoryResult =  client.createDirectory(createDirectoryRequest);
    String directoryArn = createDirectoryResult.getDirectoryArn();
    String appliedSchemaArn = createDirectoryResult.getAppliedSchemaArn();

How hierarchies are stored in a directory

The organizational chart I want to create has a simple hierarchy as shown in the following diagram. Anna belongs to both the ITStaff and Managers groups. This example demonstrates a capability of Cloud Directory that enables me to build multiple hierarchies in a single directory. These hierarchies can have their own structure and leaf nodes belonging to more than one hierarchy because lead nodes can have more than one parent.

Being able to create multiple hierarchies within a single directory gives me some flexibility in how I organize my employees. For example, I can create a hierarchy representing departments in my organization and add employees to their respective departments, as illustrated in the following diagram. I can create another hierarchy representing geographic locations and add employees to the geographic location where they work. The first step in creating this hierarchy is to create the ITStaff and Managers group objects, which is what I do in the next section.

Create group objects

I will now create the data representing my organizational chart in the directory that I created. The following code creates the ITStaff and Managers group objects, which are created under the root node of the directory.

    for (String groupName : Arrays.asList("ITStaff", "Managers")) {         
        CreateObjectRequest request = new CreateObjectRequest()
            .withDirectoryArn(directoryArn)
           // The parent of the object we are creating. We are rooting the group nodes   
           // under root object. The root object exists in all directories and the path         
           // to the root node is always "/".
           .withParentReference(new ObjectReference().withSelector("/"))
           // The name attached to the link between the parent and the child objects.
           .withLinkName(groupName)
           .withSchemaFacets(new SchemaFacet()
               .withSchemaArn(appliedSchemaArn)
               .withFacetName("Group"))
               //We specify the attributes to attach to this object.
                .withObjectAttributeList(new AttributeKeyAndValue()
                    .withKey(new AttributeKey()
                             // Name attribute for the group
                             .withSchemaArn(appliedSchemaArn)
                             .withFacetName("Group")
                             .withName("Name"))
                        // We provide the attribute value. The type used here must match the type defined in schema
                             .withValue(new TypedAttributeValue().withStringValue(groupName)));
    client.createObject(request);
    }

Create employee objects

The group objects are now in the directory. Next, I create employee objects for Anna and Bob under the ITStaff group. The following Java code creates the Anna object. Creating the Bob object is similar. When creating the Bob object, I provide different attribute values for Name, EmailAddress, and the like.

    CreateObjectRequest createAnna = new CreateObjectRequest()
                .withDirectoryArn(directoryArn)
                .withLinkName("Anna")
                .withParentReference(new ObjectReference().withSelector("/ITStaff"))
                .withSchemaFacets(new SchemaFacet()
                        .withSchemaArn(appliedSchemaArn)
                        .withFacetName("Employee"))
                .withObjectAttributeList(new AttributeKeyAndValue()
                        .withKey(new AttributeKey()
                                // Name attribute from employee facet
                                .withSchemaArn(appliedSchemaArn)
                                .withFacetName("Employee")
                                .withName("Name"))
                        .withValue(new TypedAttributeValue().withStringValue("Anna")),
                        new AttributeKeyAndValue()
                        .withKey(new AttributeKey()
                                // EmailAddress attribute from employee facet
                                .withSchemaArn(appliedSchemaArn)
                                .withFacetName("Employee")
                                .withName("EmailAddress"))
                        .withValue(new TypedAttributeValue().withStringValue("anna@somecorp.com")),
                        new AttributeKeyAndValue()
                        .withKey(new AttributeKey()
                                 // Status attribute from employee facet
                                .withSchemaArn(appliedSchemaArn)
                                .withFacetName("Employee")
                                .withName("Status"))
                        .withValue(new TypedAttributeValue().withStringValue("ACTIVE")));
     // CreateObject provides the object identifier of the object that was created.  An object identifier
       // is a globally unique, immutable identifier assigned to every object.
     String annasObjectId = client.createObject(createAnna).getObjectIdentifier();

Both the Bob and Anna objects are created under ITStaff, but Anna is also a manager and needs to be added under the Managers group. The following code does just that.

   AttachObjectRequest makeAnnaAManager = new AttachObjectRequest()
           .withDirectoryArn(directoryArn)
           .withLinkName("Anna")
           // Provide the parent object that Anna needs to be attached to using the path to the Managers object
           .withParentReference(new ObjectReference().withSelector("/Managers"))
           // Here we use the object identifier syntax to specify Anna's node. We could have used the
           // following path instead: /ITStaff/Anna. Both are equivalent.
           .withChildReference(new ObjectReference().withSelector("$" + annasObjectId));
   client.attachObject(makeAnnaAManager);

Retrieving objects in the directory

Now that I have populated my directory, I want to find a specific object. I can do that either by using the path to the object or the object identifier. I use the getObjectInformation API to first get the Anna object by specifying its path, and then I print the object identifiers of all the parents of the Anna object. I should print two parent object identifiers because Anna has both ITStaff and Managers as its parent. Here I am listing parents; however, I also can perform other operations on the object such as listing its children or its attributes. Using listChildren and listObjectAttributes, I can retrieve all the information stored in my directory.

    // First get the object for Anna
    GetObjectInformationRequest annaObjectRequest = new GetObjectInformationRequest()
           .withObjectReference(new ObjectReference().withSelector("/Managers/Anna"))
           .withDirectoryArn(directoryArn);
    GetObjectInformationResult annaObjectResult =  client.getObjectInformation(annaObjectRequest);
    // List parent objects for Anna to give her groups
    ListObjectParentsRequest annaGroupsRequest = new ListObjectParentsRequest()
           .withDirectoryArn(directoryArn)
           .withObjectReference(new ObjectReference().withSelector("$" + annaObjectResult.getObjectIdentifier()));
    ListObjectParentsResult annaGroupsResult =  client.listObjectParents(annaGroupsRequest);
    for(Map.Entry<String, String> entry : annaGroupsResult.getParents().entrySet())
    {
       System.out.println("Parent Object Identifier:" + entry.getKey());
       System.out.println("Link Name:" + entry.getValue());
    } 

Summary

In this post, I showed how to use Cloud Directory APIs to create an organizational chart with multiple hierarchies. Keep in mind that Cloud Directory offers additional functionality such as batch operations and indexing that I have not covered in this blog post. For more information, see the Amazon Cloud Directory API Reference.

If you have questions or suggestions about this blog post, start a new thread on the Directory Service forum.

– Srikanth