ScholarOneApi 1.0.0

ScholarOneEF

ASP.NET C# (Entity Framework) Library to Consume ScholarOne API

About

The purpose of this library is to provide basic functionality to retrieve data from ScholarOne by consuming their API services. This library implements a factory with a separate method to consume each ScholarOne service. The factory is configurable for project requirements, and enforces that required parameters are provided. API responses returned from ScholarOne are left as raw strings for developers to process as needed.

This library was developed in Microsoft Visual Studio and contains one class library written in C# using Entity Framework 4.7.2. There are no dependencies on any other resources. There is one assembly in this library.

This repository is not affiliated with or supported by Clarivate or ScholarOne. Using this library requires a user name and API key which must be obtained through ScholarOne support. No guarantees are provided that this repository will be kept up to date with any future changes in the ScholarOne API.

License

This software is provided under the MIT open source license.

Copyright 2022 Thomas Eheman

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Digest Authentication

ScholarOne API services use digest authentication. ASP.NET is capable of consuming services using digest authentication by providing credentials. However, there is an obscure bug when attempting to consume services using digest authentication with query parameters in the Uri. Digest standards require that the Uri in the authorization header match the Uri being requested, but ASP.NET leaves out the query parameters in the authorization header. This requires a work around in ASP.NET in order to consume ScholarOne API, and was the main impetus of this library.

This library implements custom processing of the authorization header, with built in support for using HttpClient or WebClient classes to make http requests. Projects are free to make custom implementations of the BaseFactory class with their own implementations of the http requests.

Using the Library

Initialize the Factory

The included factory has several constructors. The minimum requirements are a user name, api key, and the site name. The settings can also be updated after factory initialization. Initializing the factory and the default value of the optional properties are shown below.

// Initialize factory with minimum requirements  
var factory = new ScholarOneApi.Factory("user name", "api key", "site name");  

// configure the factory  

// factory defaults  
factory.ResponseType = ScholarOneApi.ResponseTypeEnum.xml; 
factory.LocaleId = ScholarOneApi.LocaleIdEnum.English;  
factory.Environment = ScholarOneApi.EnvironmentEnum.Integration;  
factory.PropogateErrors = true;  

// other settings  
factory.ExternalId = "my external id";  

The configurable factory settings are either a simple data type or an enum.

Retrieve Data

Each ScholarOne API resource has its own method call in the factory. Use the factory method that corresponds the ScholarOne API that needs to be consumed. These methods are asynchronous.

// consume API
var submissionIds = new List<string> { "submission id 1", "submission id 2" };
var result = await factory.GetAuthorFullBySubmissionId(submissionIds);

List of factory methods

• GetAuthorFullBySubmissionId
• GetAuthorFullByDocumentId
• GetAuthorBasicBySubmissionId
• GetAuthorBasicByDocumentId
• GetReviewerInfoFullBySubmissionId
• GetReviewerInfoFullByDocumentId
• GetSubmissionInfoBasicBySubmissionId
• GetSubmissionInfoBasicByDocumentId
• GetSubmissionFullBySubmissionId
• GetSubmissionFullByDocumentId
• GetStaffInfoFullBySubmissionId
• GetStaffInfoFullByDocumentId
• GetSubmissionVersionsBySubmissionId
• GetSubmissionVersionsByDocumentId
• GetPersonInfoBasicId
• GetPersonInfoBasicEmail
• GetPersonInfoFullId
• GetPersonInfoFullEmail
• GetDecisionCorrespondenceFullSubmissionId
• GetDecisionCorrespondenceFullDocumentId
• GetExternalDocumentIdsFull

Process the result

The factory methods return an object referred to as a "service result" in this library. Each method returns its own service result object, but they all have common properties found in the table below.

Processing the data depends on the format of the data requested. For example, an XML response can be manipulated with the XmlDocument class.

// Load the Scholar One XML
var xmlDoc = new System.Xml.XmlDocument();
xmlDoc.LoadXml(result.Response);

// Do something with the XML

The Response property can be an empty string, and must be handled by the application code.

Customizing the Factory

The factory provided is optional. Developers are free to implement their own factory class by overriding the BaseFactory class. There are two methods that must be implemented by the child class, as described in the table below.

A basic implementation of the factory class can be started from the code below.

public class CustomFactory : ScholarOneApi.BaseFactory
{
    public CustomFactory(string user, string password, string siteName) : base(user, password, siteName)
    {
        // Set factory settings
    }

    protected override Task<string> GetInitialAuthorizationHeader(Uri uri)
    {
        // Implement custom GET request to the URI specified
        // return the authorization header of the ScholarOne response

        throw new NotImplementedException();
    }

    protected override Task<string> GetAuthorizedResponse(Uri uri, string authorizationHeader)
    {
        // Implement custom GET request to the URI specified
        // The authorization header of the request must be set to the authorizationHeader parameter
        // return the response body from ScholarOne
            
        throw new NotImplementedException();
    }
}