api.admin.api Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ApiGen Show documentation
null
There is a newer version: 3.0.4
[ The Admin API is used to manipulate and access the low level entities in Rapture. Typically the methods in this API
are only used during significant setup events in a Rapture environment.]
api(Admin) {
    [This function retrieves the system properties in use for this instance of Rapture. As system properties
    are often used to control external connectivity, a client can determine the inferred connectivity endpoints
    by using this api call. It returns a map from system property name (the key) to value. You cannot modify the
    system properties of Rapture through the api, they are set by the administrator as part of the general setup of a Rapture
    system. Note that this call returns the properties for the actual end point that the client is connected to, it is not necessarily true that
    the same properties will be set for every API endpoint.]
    
    @entitle=/admin/main
    @public Map(String, String) getSystemProperties(List(String) keys);

    [Rapture is a hierarchical set of repositories, and this method returns the config of the top most level - that used
    for general config and temporary (transient) values such as sessions. In clustered mode these configs would
    be referencing shared storage, and in test mode they would normally refer to in-memory versions of the config. 
    The manipulation of the top level config can be performed through the Bootstrap API.]
    @entitle=/admin/main
	@public List(RepoConfig) getRepoConfig();

    [When a user logs into Rapture they create a transient session and this method is a way of 
    retrieving all of the sessions for a given user. The CallingContext is a common object 
    passed around Rapture api calls.]
    
    @entitle=/admin/main
    @public List(CallingContext) getSessionsForUser(String user);

    [This method removes a user from this Rapture system. The user is removed from all entitlement groups also. The actual
    user definition is retained and marked as inactive (so the user cannot login). This is because the user may still be 
    referenced in audit trails and the change history in type repositories.]
    @entitle=/admin/main
    @public void deleteUser(String userName);
    
    [This method destroys a user record. The user must have been previously disabled using 'deleteUser' before this method 
    may be called. This is a severe method that should only be used in non-production machines or to correct an administrative
    error in creating an account with the wrong name before that account has been used. Reference to the missing user may still
    exist, and may not display properly in some UIs]
    @entitle=/admin/main
    @public void destroyUser(String userName);

    [This method restores a user that has been deleted]
    @entitle=/admin/main
    @public void restoreUser(String userName);

    [This method adds a user to the Rapture environment. The user will be in no entitlement groups by default. The password
    field passed is actually the MD5 hash of the password - or at least the same hash function that will be applied when
    logging in to the system (the password is hashed, and then hashed again with the salt returned during the login protocol).]
    @entitle=/admin/main
    @public void addUser(String userName, String description, String hashPassword, String email);

    [Verify user by providing a secret token]
    @entitle=/admin/main
    @public Boolean verifyUser(String userName, String token);

    [This api call can be used to determine whether a given user exists in the Rapture system. Only system administrators can use this api call.]
    @entitle=/admin/main
    @public Boolean doesUserExist(String userName);

    [Retrieve a single user given their name.]
    @entitle=/admin/main
    @public RaptureUser getUser(String userName);

    [ Generates an api user, for use in connecting to Rapture in a relatively opaque way using a shared secret. An api user can log in with their access key without a password.]
    @entitle=/admin/main
    @public RaptureUser generateApiUser(String prefix, String description);

    [This method gives an administrator the ability to reset the password of a user. The user will have the new password passed. The newHashPassword parameter should be an MD5 
    of the new password - internally this will be hashed further against a salt for this user.]
    @entitle=/admin/main
    @public void resetUserPassword(String userName, String newHashPassword);

    [Creates password reset token and emails it to the user]
    @entitle=/admin/main
    @public String createPasswordResetToken(String username);

    [Creates registration token and emails it to the user]
    @entitle=/admin/main
    @public String createRegistrationToken(String username);

    [Cancels password reset token]
    @entitle=/admin/main
    @public void cancelPasswordResetToken(String username);

    [Emails user]
    @entitle=/admin/main
    @public void emailUser(String userName, String emailTemplate, Map templateValues);

    [This method updates user email.]
    @entitle=/admin/main
    @public void updateUserEmail(String userName, String newEmail);
    

   /*
    * Templates
    */

   [This function adds a template to the Rapture system. A template is a simple way of registering predefined configs that can be used to automatically generate configs for repositories, queues, and the like. 
   Templates use the popular StringTemplate library for merging values into a text template.]
   @entitle=/admin/main
   @public void addTemplate(String name, String template, Boolean overwrite);

   [This method executes a template, replacing parts of the template with the passed parameters to create a new string.]
   @entitle=/admin/main
   @public String runTemplate(String name, String parameters);

   [This method returns the definition of a template.]
   @entitle=/admin/main
   @public String getTemplate(String name);

   [Copies the data from one DocumentRepo to another. The target repository is wiped out before hand if 'wipe' is set to true. The target must already exist when this method is called.]
   @entitle=/admin/main
   @public void copyDocumentRepo(String srcAuthority, String targAuthority, Boolean wipe);

   [Use this method to add an IP address to a white list of allowed IP addresses that can log in to this Rapture environment. Once set only IP addresses in this ipAddress list can access Rapture. By default there are no whitelist IP addresses defined which actually means that all IP addresses are allowed.]
   @entitle=/admin/main
   @public void addIPToWhiteList(String ipAddress);

   [Use this method to remove an IP address from a white list]
   @entitle=/admin/main
   @public void removeIPFromWhiteList(String ipAddress);

   [Use this method to return the IP white list]
   @entitle=/admin/main
   @public List(String) getIPWhiteList();

   [This method retrieves all of the registered users in the system]
   @entitle=/admin/main
   @public List(RaptureUser) getAllUsers();
 
   [This method kicks off a process that will migrate a DocumentRepo to an alternate config. A temporary type will be created with the new config,
    the old type will be locked for modifications and then all of the documents in the existing type will be copied to the new type, with the metadata intact.
    Optionally a number of historical versions will be kept if the source repository (and target) support it. Once all of the data has been copied the config
    attached to each type will be swapped and the type released for access. The temporary type will then be dropped.]
   @entitle=/admin/main
   @public void initiateTypeConversion(String raptureURI, String newConfig, int versionsToKeep);

   [Set the archive config for a type]
   @entitle=/admin/main
   @public void putArchiveConfig(String raptureURI, TypeArchiveConfig config);

   [Retrieve the archive config for a authority]
   @entitle=/admin/main
   @public TypeArchiveConfig getArchiveConfig(String raptureURI);

   [Delete the archive config for a authority]
   @entitle=/admin/main
   @public void deleteArchiveConfig(String raptureURI);

   [A general purpose function that tests (or refreshes) the api connection to Rapture with no side effects.]
   @entitle=/admin/main
   @public Boolean ping();

   [This function adds values to the metadata field of the CallingContext. It's used to hold values specific to this connection. 
   Since it's set by the caller the values cannot be considered entirely trusted, and private or secure data such as passwords shouldn't be stored in here.
   If overwrite is false and an entry already exists then an exception should be thrown]
   @entitle=/admin/main
   @public void addMetadata(Map values, Boolean overwrite);
   
   [Set the MOTD (message of the day) for this environment. Setting to a zero length string implies that there is no message of the day]
   @entitle=/admin/main
   @public void setMOTD(String message);
   
   [Retrieve the MOTD]
   @entitle=/everyone
   @public String getMOTD();
   
   [Set the name of this environment]
   @entitle=/admin/main
   @public void setEnvironmentName(String name);
   
   [Set the properties of this environment. Usually for displaying then name (e.g. BANNER_COLOR)]
   @entitle=/admin/main
   @public void setEnvironmentProperties(Map properties);
   
   [Get the name of this environment]
   @entitle=/admin/main
   @public String getEnvironmentName();
   
   [Get the properties of this environment]
   @entitle=/admin/main
   @public Map getEnvironmentProperties();
   
   [Encode a String using the default encoding mechanism]
   @entitle=/admin/main
   @public String encode(String toEncode);
   
   [Create a URI with proper encoding given a path and a leaf. Normal URI characters such as : or / in the path will not be encoded]
   @entitle=/admin/main
   @public String createURI(String path, String leaf);
   
   [Create a URI with proper encoding given a list of elements. The return value will begin with // Each element will be encoded 
   (including all punctuation characters) and the elements joined together separated by /]
   @entitle=/admin/main
   @public String createMultipartURI(List elements);
   
   [Decode the supplied String according to the URI encoding/decoding rules]
   @entitle=/admin/main
   @public String decode(String encoded);
   
   [Find the groups for a given user and return just the names]
   @entitle=/admin/main
   @public List(String) findGroupNamesByUser(String username);
}