GlobalLink.GLCapi.Rest 1.0.8

Creating the Project Director API client Object

Creating the Project Director API client is done via the ProjectDirectorApiClient class. First, you must provide your Project Director credentials and PD instance URL. This is done via the ProjectDirectorConfig class. Once you instantiate a ProjectDirectorConfig() object, with all the necessary arguments, pass that object to the ProjectDirectorApiClient() constructor.

    ProjectDirectorConfig config = new ProjectDirectorConfig(
            "https://pd-instance-url.com", 
            "pd_user",
            "pd_password", 
            "basicAuthUser", 
            "basicAuthPass",
            "user-agent-name"
            );

    ProjectDirectorApiClient api = new ProjectDirectorApiClient(config);

The client will automatically log in to Project Director and obtain a token. It will also auto refresh the token when the current token expires.

Optionally you can create ProjectDirectorConfig with auth token if you already have one.

    ProjectDirectorConfig config = new ProjectDirectorConfig(
            "https://pd-instance-url.com", 
            "token",
            "user-agent-name"
            );

    ProjectDirectorApiClient api = new ProjectDirectorApiClient(config);

Project Director API

More information about PD's REST API can be found here

• API Documentation
• Swagger

Examples

Get submission information

public static void main(String[]args) {
    ProjectDirectorConfig config = new ProjectDirectorConfig(
        "https://pd-instance-url.com",
        "pd_user",
        "pd_password",
        "basicAuthUser",
        "basicAuthPass",
        "user-agent-name"
    );
    
    ProjectDirectorApiClient api = new ProjectDirectorApiClient(config);
    
    int submissionId = 1234;
    FullSubmission sub = api.GetSubmissionById(submissionId);
}

Retrieving all projects available to the user

public static void main(String[]args) {
    ProjectDirectorConfig config = new ProjectDirectorConfig(
        "https://pd-instance-url.com",
        "pd_user",
        "pd_password",
        "basicAuthUser",
        "basicAuthPass",
        "user-agent-name"
    );
    
    ProjectDirectorApiClient api = new ProjectDirectorApiClient(config);
    // Empty search. Will retrieve all projects available to the user.    
    List<Project> projects = client.GetProjects();
    
    // GetProjects() optionally gets GetProjectsRequest object which can help customizing request
    // Sort and order project results
    List<Project> projects = client.GetProjects(new GetProjectsRequest() { orderBy = enums.ProjectsOrderByEnum.enabled, orderType = enums.OrderTypeEnum.ASCENDING });
    // Get 10 projects from page 10
    List<Project> projects = client.GetProjects(new GetProjectsRequest() { pageNumber=10, pageSize=10 });
    // Get 10 projects from page 10 which are from "ORG" organization and only my
    List<Project> projects = client.GetProjects(new GetProjectsRequest() { pageNumber=10, pageSize=10, onlyMyProjects=true, organizationName="ORG" });
}

Retrieving one project

public static void main(String[]args) {
    ProjectDirectorConfig config = new ProjectDirectorConfig(
        "https://pd-instance-url.com",
        "pd_user",
        "pd_password",
        "basicAuthUser",
        "basicAuthPass",
        "user-agent-name"
    );
    
    ProjectDirectorApiClient api = new ProjectDirectorApiClient(config);
    
    FullProject project = api.GetProjectById(1234);
}

Retrieve all custom attributes in a project

public static void main(String[]args) {
    ProjectDirectorConfig config = new ProjectDirectorConfig(
        "https://pd-instance-url.com",
        "pd_user",
        "pd_password",
        "basicAuthUser",
        "basicAuthPass",
        "user-agent-name"
    );
    
    ProjectDirectorApiClient api = new ProjectDirectorApiClient(config);
    
    List<CustomAttribute> customAttributes = api.GetProjectCustomAttributes(1234);
}

Owner information

Organization users can be set as owners of a submission.

public static void main(String[]args) {
    ProjectDirectorConfig config = new ProjectDirectorConfig(
        "https://pd-instance-url.com",
        "pd_user",
        "pd_password",
        "basicAuthUser",
        "basicAuthPass",
        "user-agent-name"
    );
    
    ProjectDirectorApiClient api = new ProjectDirectorApiClient(config);

    // Use the id of the organization user to set the owners of a submission
    List<OrganizationUsers> = api.GetProjectOrgUsers(1234);
}

Creating a submission

public static void main(String[]args) {
    ProjectDirectorConfig config = new ProjectDirectorConfig(
        "https://pd-instance-url.com",
        "pd_user",
        "pd_password",
        "basicAuthUser",
        "basicAuthPass",
        "user-agent-name"
    );
    
    ProjectDirectorApiClient client = new ProjectDirectorApiClient(config);

    var fullProject = client.GetProjectById(projectId);
    var users = client.GetProjectOrgUsers(projectId);
        
    // Set batch information
    var batchInfos = new List<BatchInfo>();
    batchInfos.Add(new BatchInfo(BATCH_NAME, new List<string>() { fullProject.projectLanguageDirections[0].targetLanguage }, fullProject.workflowDefinitions[0].id, "TXML"));
    // Create request with submission name, dueDate, sourceLocale and other additional info
    var createSubmissionRequest = new CreateSubmissionRequest(SUB_NAME, DateTime.Now.AddDays(5), fullProject.projectLanguageDirections[0].sourceLanguage, batchInfos, fullProject.projectId)
    {
        instructions = INSTRUCTIONS,
        background = BACKGROUND,
        techTracking = new TechTrackingInfo("glc.rest.test", "1", "1.1", null),
        owners = new List<Int64>() { users[0].userId }
    };
    CreateSubmissionResponse createResponse = client.CreateSubmission(createSubmissionRequest);
        
}

Uploading files

public static void main(String[]args) {
    ProjectDirectorConfig config = new ProjectDirectorConfig(
        "https://pd-instance-url.com",
        "pd_user",
        "pd_password",
        "basicAuthUser",
        "basicAuthPass",
        "user-agent-name"
    );
    
    ProjectDirectorApiClient client = new ProjectDirectorApiClient(config);

    // upload parsable with byte data
    string xml = "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?><pages><page itemid=\"294_309\" type=\"Block\"><property name=\"Categorytype\"><![CDATA[type one]]></property></page></pages>"; 
    var uploadParsableRequest = new UploadParsableRequest("sample.xml", Encoding.UTF8.GetBytes(xml), BATCH_NAME, FILE_FORMAT, false);
    var uploadResponse = client.UploadParsable(createResponse.submissionId, uploadParsableRequest);
    // or upload parsable with file path
    //var uploadParsableRequest = new UploadParsableRequest("path/to/file", BATCH_NAME, FILE_FORMAT, false);
    //var uploadResponse = client.UploadParsable(createResponse.submissionId, uploadParsableRequest);

    // wait for upload process to be finished
    client.WaitForProcessed(createResponse.submissionId);
    // optionally client.UploadParsable() has argument waitForProcessed. If set to true, then client will wait automatically
}

Save Submission

Once the submission is created it will not be visible in the PD UI. Call saveSubmission(int subId, boolean autoStart) to make it visible in the UI. If autoStart is set to false, an additional call to startSubmission(int subId) must be made in order to move the submission from On Hold folder to the Active folder.

public static void main(String[]args) {
    ProjectDirectorConfig config = new ProjectDirectorConfig(
        "https://pd-instance-url.com",
        "pd_user",
        "pd_password",
        "basicAuthUser",
        "basicAuthPass",
        "user-agent-name"
    );

    ProjectDirectorApiClient api = new ProjectDirectorApiClient(config);
    
    /**
     * The submission will not be visible in PD after calling the create endpoint.
     * You must call saveSubmission to make it visible. In this example autostart is set to true.
     * If autoStart is set to false, you'll have to call startSubmission() to move the submission to the Active
     * folder in the UI
     */
    var saveSubmissionResponse = api.SaveSubmission(createResponse.submissionId, true);
}

Check for completed targets in two specific languages

public static void main(String[]args) {
    ProjectDirectorConfig config = new ProjectDirectorConfig(
        "https://pd-instance-url.com",
        "pd_user",
        "pd_password",
        "basicAuthUser",
        "basicAuthPass",
        "user-agent-name"
    );
    
    ProjectDirectorApiClient api = new ProjectDirectorApiClient(config);

    List<Target> completedTargets = api.GetTargetsBySubmissionId(subId, new GetTargetsBySubmissionIdRequest() { 
        status = TargetStatusEnum.PROCESSED,
        targetLanguage = new List<string>() { "fr-FR", "de-DE" } 
    });
}

Check for completed submissions with source languages

public static void main(String[]args) {
    ProjectDirectorConfig config = new ProjectDirectorConfig(
        "https://pd-instance-url.com",
        "pd_user",
        "pd_password",
        "basicAuthUser",
        "basicAuthPass",
        "user-agent-name"
    );
    
    ProjectDirectorApiClient api = new ProjectDirectorApiClient(config);

    List<Submission> submissions = api.GetSubmissions(new GetSubmissionsRequest() { 
        sourceLanguages = new List<string>() { "en", "en-US", "en-GB" },
        statuses = new List<SubmissionStatusEnum>() { SubmissionStatusEnum.PROCESSED} 
    });

}

Download completed targets

public static void main(String[]args) {
    ProjectDirectorConfig config = new ProjectDirectorConfig(
        "https://pd-instance-url.com",
        "pd_user",
        "pd_password",
        "basicAuthUser",
        "basicAuthPass",
        "user-agent-name"
    );
    
    ProjectDirectorApiClient api = new ProjectDirectorApiClient(config);

    var targetIds = new List<Int64>() { 1234, 8890 };
    // request target download with automatically wait for processing finish
    //var requestDownloadResponse = api.RequestDownloadTarget(subId, new RequestDownloadRequest(targetIds), true);
    // request target download without waiting for processing finish
    var requestDownloadResponse = api.RequestDownloadTarget(subId, new RequestDownloadRequest(targetIds));
    // Get download id
    String downloadId = submissionDownload.getDownloadId();
    //Check if file is avalailable for download. Not need to check isDownloadReady if auto-wait flag was provided
    if (api.IsDownloadReady(1234, requestDownloadResponse.downloadId)) {
        byte[] data = api.DownloadTarget(requestDownloadResponse.downloadId);
        // Do something with the data
    }

}

Mark targets as delivered

public static void main(String[]args) {
    ProjectDirectorConfig config = new ProjectDirectorConfig(
        "https://pd-instance-url.com",
        "pd_user",
        "pd_password",
        "basicAuthUser",
        "basicAuthPass",
        "user-agent-name"
    );
    
    ProjectDirectorApiClient api = new ProjectDirectorApiClient(config);

    var targetIds = new List<Int64>() { 5467, 4563 };
    // Mark targets: 5467 and 4563 as delivered
    ConfirmTargetDeliveryResponse confirmResponse = client.ConfirmTargetDelivery(1234, new ConfirmTargetDeliveryRequest(targetIds));
    // See which targets failed to deliver
    List<Int64> failed = confirmResponse.failedToDeliverTargets;
    // See which targets were marked as delivered
    List<Int64> success = confirmResponse.successfullyDeliveredTargets; 
}

Features

Proxy support

ProjectDirectorApiClient supports working via proxies. It is possible to specify one or several proxies at once. ApiClient will automatically find working proxy and use if. If proxy stops working and additional proxies are configured - it is possible for ApiClient to automaticaly switch to other proxy in list. To make this work you need to set ProjectDirectorConfig.checkConnectionOnEachRequest to true

public static void main(String[]args) {
    ProjectDirectorConfig config = new ProjectDirectorConfig("url", "pd_user", "pd_pass",  "basicAuthUser", "basicAuthPass", "user-agent-name");
    config.checkConnectionOnEachRequest = true;
    config.proxyConfigs = new List<ProjectDirectorProxyConfig>()
    {
        new ProjectDirectorProxyConfig("http://proxy.com"),
        new ProjectDirectorProxyConfig("http://proxy_auth.com:8080", "user", "password"),
        new ProjectDirectorProxyConfig("host.com", 80),
        new ProjectDirectorProxyConfig("172.16.0.1", 80, "user", "password")
    };
    
    ProjectDirectorApiClient api = new ProjectDirectorApiClient(config); 
}

Custom request headers

ProjectDirectorApiClient allows client to add custom headers to requests. They can be specified in ProjectDirectorConfig - in this case headers will be added to all requests.

public static void main(String[]args) {
    ProjectDirectorConfig config = new ProjectDirectorConfig("url", "pd_user", "pd_pass",  "basicAuthUser", "basicAuthPass", "user-agent-name");
    var headers = new Dictionary<string, string>();
    headers.Add("header_one", "value_one");
    headers.Add("header_two", "value_two");
    config.customHeaders = headers;
    
    ProjectDirectorApiClient api = new ProjectDirectorApiClient(config); 
}

Logging

It is possible to get information about last request json which was sent to server as well as last response which was received from server. ProjectDirectorApiClient provides two methods to get this info.

public static void main(String[]args) {
    ProjectDirectorConfig config = new ProjectDirectorConfig("url", "pd_user", "pd_pass",  "basicAuthUser", "basicAuthPass", "user-agent-name");
    ProjectDirectorApiClient api = new ProjectDirectorApiClient(config); 

    api.GetProjects();

    string lastRequestJson = client.getLastRequestJson();
    string lastResponseJson = client.getLastResponseJson();
}

Extendability

Library can be extended with additional custom PD api operations. ProjectDirectorApiClient provides method "doRequest(RestOperation operation)" which takes RestOperation as argument. glcapi.rest.operation.core.RestOperation is an abstract class which is extended by all already existing operations. Creating and using new api operation will require following steps

1. Extend RestOperation class and implement all abstract methods:
   • GetOperationUrl() - relative request url, e.g. "rest/v0/projects"
   • GetRequestMethod() - request method. e.g. RestSharp.Method.Get
   • GetRequestObject() - any object which will be serialized to json and set as request body. Can be null
   • GetRequestJson() - json to be used as request body. If not null then GetRequestObject() will be ignored. Can be null
   • GetResponseType() - type of response object. Response will be deserialized to this type. E.g. typeof(List<Project>) If GetResponseType() is typeof(byte[]) then response will be returned as byte[] (e.g. downloading byte data) If GetResponseType() is null then response will be returned as string
2. Create ProjectDirectorApiClient instance as usual
3. Use client.doRequest(RestOperation). E.g. List<Project> = (List<Project>)api.doRequest(new CustomRestOperation());

For cases when custom RestOperation doesn't need request body json but needs query parameters, it should extend glcapi.rest.operation.core.BasicParametersOperation. It adds abstact method "Dictionary<string, object> getRequestParameters()" where you should put all query parameters. Also it has method GetParameterType() which defaults to ParameterType.QueryString, but can be overriden with e.g. ParameterType.RequestBody if parameters should be sent as multipart form data.

Additionaly, custom RestOperation can use operation specific customHeaders. They will take precedence over config.customHeaders

Library structure

glcapi.rest.operation - each class is an implementation of RestOperation and represents one PD API endpoint with url/request/response glcapi.rest.operation.core - basic abstact classes for RestOperations glcapi.rest.request - contains request objects for ProjectDirectorApiClient methods. Objects are used to add additional parameters or json to API operations glcapi.rest.enums - enums wtih possible statuses, orderBy, orderType etc. glcapi.rest.entity - basic PD objects that will be returned in response glcapi.rest.exception - exceptions - ConfigException - thrown when ProjectDirectorConfig is invalid or some requests doesn't pass internal validation (e.g. empty field, field value length) - OperationException - thrown only when request to download target is sent but download is not ready after specified timeout - OperationResultException - thrown when processing response - when response code is not 200 or response content is empty while it was expected by operation