R/AutoGeneratedDefinitions.R

In OHDSI/ROhdsiWebApi: Interacting With an OHDSI WebApi Instance

# Copyright 2022 Observational Health Data Sciences and Informatics
#
# This file is part of FeatureExtraction
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.


# This file has been autogenerated. Do not change by hand.


#' Get the meta data for ConceptSet definitions. 
#' @details
#' Get the meta data of WebApi specifications such as id, name, created/modified details, hash object,
#' etc. from WebApi for ConceptSet. This function is useful to retrieve the current ConceptSet
#' specifications.
#'
#' @template BaseUrl
#' @return
#' A tibble of specification metadata for ConceptSet. Note: modifiedDate and createdDate are returned
#' as text/character.
#'
#' @examples
#' \dontrun{
#' getConceptSetDefinitionsMetaData(baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getConceptSetDefinitionsMetaData <- function(baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  metaData <- getDefinitionsMetadata(baseUrl = baseUrl, category = c("conceptSet"))
  return(metaData)
}


#' is ConceptSet id a valid definition in the WebApi. 
#' @details
#' Checks if a set of id for a ConceptSet is valid. The following checks are performed. 1) checks if
#' all the ids exists in the WebApi i.e. valid.
#'
#' @template BaseUrl
#' @param conceptSetIds   A list of integer id(s) of the ConceptSet to be tested for validity.
#' @return
#' A logical vector indicating if an ID is valid.
#'
#' @examples
#' \dontrun{
#' isValidConceptSetId(conceptSetIds = c(13242, 3423, 34), baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
isValidConceptSetId <- function(conceptSetIds, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- isValidId(baseUrl = baseUrl, category = "conceptSet", ids = conceptSetIds)
  return(result)
}


#' Get ConceptSet id definition. 
#' @details
#' Obtain the ConceptSet definition from WebAPI for a given ConceptSet id
#'
#' @template BaseUrl
#' @param conceptSetId   An integer id representing the id that uniquely identifies a ConceptSet
#'                       definition in a WebApi instance.
#' @return
#' An R object representing the ConceptSet definition
#'
#' @examples
#' \dontrun{
#' getConceptSetDefinition(conceptSetId = 13242, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getConceptSetDefinition <- function(conceptSetId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- getDefinition(id = conceptSetId, baseUrl = baseUrl, category = "conceptSet")
  return(result)
}


#' Delete ConceptSet id definition. 
#' @details
#' Delete the ConceptSet definition from WebAPI for a given ConceptSet id
#'
#' @template BaseUrl
#' @param conceptSetId   An integer id representing the id that uniquely identifies a ConceptSet
#'                       definition in a WebApi instance.
#' @return
#' None, unless error.
#'
#' @examples
#' \dontrun{
#' deleteConceptSetDefinition(conceptSetId = 13242, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
deleteConceptSetDefinition <- function(conceptSetId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- deleteDefinition(baseUrl = baseUrl, id = conceptSetId, category = "conceptSet")
  return(result)
}


#' Check if ConceptSet definition name exists. 
#' @details
#' Check if a string name already exists in the WebApi as a ConceptSet definition name.
#'
#' @template BaseUrl
#' @param conceptSetName   A string name for the ConceptSet to be checked.
#' @return
#' If found, the function will return a tibble with details of the specification. If not found, FALSE
#' will be returned.
#'
#' @examples
#' \dontrun{
#' existsConceptSetName(conceptSetName = "this text string needs to be checked",
#'                      baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
existsConceptSetName <- function(conceptSetName, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  definitionsMetaData <- getConceptSetDefinitionsMetaData(baseUrl = baseUrl)
  matched <- definitionsMetaData %>% dplyr::filter(.data$name == conceptSetName)
  if (nrow(matched) > 0) {
    return(matched)
  } else {
    FALSE
  }
}


#' Detect the presence of string matched ConceptSet definitions. 
#' @details
#' Detect string matched ConceptSet definition names from the WebApi, and retrieve metadata
#' definitions.
#'
#' @template BaseUrl
#' @param pattern   A pattern to look for. See \link[stringr]{str_detect} for details.
#' @param negate    If TRUE, return non-matching elements. See \link[stringr]{str_detect} for details.
#' @return
#' FALSE if no matches. If matched - output from \link[ROhdsiWebApi]{getConceptSetDefinitionsMetaData}
#'
#' @examples
#' \dontrun{
#' detectConceptSets(pattern = "this text string to search in pattern",
#'                   baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
detectConceptSetsByName <- function(pattern, negate = FALSE, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  definitionsMetaData <- getConceptSetDefinitionsMetaData(baseUrl = baseUrl)
  matched <- definitionsMetaData %>% dplyr::filter(stringr::str_detect(string = .data$name,
                                                                       pattern = pattern,
                                                                       negate = negate))
  if (nrow(matched) > 0) {
    return(matched)
  } else {
    return(FALSE)
  }
}




#' Post ConceptSet definition. 
#' @details
#' Post ConceptSet definition to WebAPI
#'
#' @template BaseUrl
#' @param name                   A valid name for the definition. WebApi will use this name (if valid)
#'                               as the name of the definition. WebApi checks for validity, such as
#'                               uniqueness, absence of unacceptable character etc. An error might be
#'                               thrown.
#' @param conceptSetDefinition   An R list object containing the expression for the specification. This
#'                               will be converted to JSON expression by function and posted into the
#'                               WebApi. Note: only limited checks are performed in R to check the
#'                               validity of this expression.
#' @return
#' This function will return a dataframe object with one row describing the posted WebApi expression
#' and its details. If unsuccessful a STOP message will be shown.
#'
#' @examples
#' \dontrun{
#' postConceptSetDefinition(name = "new valid name",
#'                          conceptSetDefinition = definition,
#'                          baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
postConceptSetDefinition <- function(name, conceptSetDefinition, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- postDefinition(name = name,
                           baseUrl = baseUrl,
                           category = "conceptSet",
                           definition = conceptSetDefinition)
  return(result)
}


#' Update a ConceptSet definition. 
#' @details
#' Update a ConceptSet definition.
#'
#' @template BaseUrl
#' @param conceptSetDefinition   An R list object containing the expression for the specification. Must
#'                               include id, name and expression. This will be converted to JSON
#'                               expression by function and posted into the WebApi. The definition will
#'                               be checked against the WebApi instance for errors
#'
#' @examples
#' \dontrun{
#' definition <- getConceptSetDefinition(id = 13242,
#'                                       baseUrl = "http://server.org:80/WebAPI",
#'                                       category = conceptSet)
#' definition$name <- "My new name for this"
#' updateConceptSet(conceptSetDefinition, baseUrl, category = "cohort")
#' }
#' @export
# Check name
updateConceptSetDefinition <- function(conceptSetDefinition, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- updateDefinition(baseUrl = baseUrl,
                             definition = conceptSetDefinition,
                             category = "conceptSet")
  return(result)
}

#' Get the meta data for Cohort definitions. 
#' @details
#' Get the meta data of WebApi specifications such as id, name, created/modified details, hash object,
#' etc. from WebApi for Cohort. This function is useful to retrieve the current Cohort specifications.
#'
#' @template BaseUrl
#' @return
#' A tibble of specification metadata for Cohort. Note: modifiedDate and createdDate are returned as
#' text/character.
#'
#' @examples
#' \dontrun{
#' getCohortDefinitionsMetaData(baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getCohortDefinitionsMetaData <- function(baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  metaData <- getDefinitionsMetadata(baseUrl = baseUrl, category = c("cohort"))
  return(metaData)
}


#' is Cohort id a valid definition in the WebApi. 
#' @details
#' Checks if a set of id for a Cohort is valid. The following checks are performed. 1) checks if all
#' the ids exists in the WebApi i.e. valid.
#'
#' @template BaseUrl
#' @param cohortIds   A list of integer id(s) of the Cohort to be tested for validity.
#' @return
#' A logical vector indicating if an ID is valid.
#'
#' @examples
#' \dontrun{
#' isValidCohortId(cohortIds = c(13242, 3423, 34), baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
isValidCohortId <- function(cohortIds, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- isValidId(baseUrl = baseUrl, category = "cohort", ids = cohortIds)
  return(result)
}


#' Get Cohort id definition. 
#' @details
#' Obtain the Cohort definition from WebAPI for a given Cohort id
#'
#' @template BaseUrl
#' @param cohortId   An integer id representing the id that uniquely identifies a Cohort definition in
#'                   a WebApi instance.
#' @return
#' An R object representing the Cohort definition
#'
#' @examples
#' \dontrun{
#' getCohortDefinition(cohortId = 13242, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getCohortDefinition <- function(cohortId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- getDefinition(id = cohortId, baseUrl = baseUrl, category = "cohort")
  return(result)
}


#' Delete Cohort id definition. 
#' @details
#' Delete the Cohort definition from WebAPI for a given Cohort id
#'
#' @template BaseUrl
#' @param cohortId   An integer id representing the id that uniquely identifies a Cohort definition in
#'                   a WebApi instance.
#' @return
#' None, unless error.
#'
#' @examples
#' \dontrun{
#' deleteCohortDefinition(cohortId = 13242, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
deleteCohortDefinition <- function(cohortId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- deleteDefinition(baseUrl = baseUrl, id = cohortId, category = "cohort")
  return(result)
}


#' Check if Cohort definition name exists. 
#' @details
#' Check if a string name already exists in the WebApi as a Cohort definition name.
#'
#' @template BaseUrl
#' @param cohortName   A string name for the Cohort to be checked.
#' @return
#' If found, the function will return a tibble with details of the specification. If not found, FALSE
#' will be returned.
#'
#' @examples
#' \dontrun{
#' existsCohortName(cohortName = "this text string needs to be checked",
#'                  baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
existsCohortName <- function(cohortName, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  definitionsMetaData <- getCohortDefinitionsMetaData(baseUrl = baseUrl)
  matched <- definitionsMetaData %>% dplyr::filter(.data$name == cohortName)
  if (nrow(matched) > 0) {
    return(matched)
  } else {
    FALSE
  }
}


#' Detect the presence of string matched Cohort definitions. 
#' @details
#' Detect string matched Cohort definition names from the WebApi, and retrieve metadata definitions.
#'
#' @template BaseUrl
#' @param pattern   A pattern to look for. See \link[stringr]{str_detect} for details.
#' @param negate    If TRUE, return non-matching elements. See \link[stringr]{str_detect} for details.
#' @return
#' FALSE if no matches. If matched - output from \link[ROhdsiWebApi]{getCohortDefinitionsMetaData}
#'
#' @examples
#' \dontrun{
#' detectCohorts(pattern = "this text string to search in pattern",
#'               baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
detectCohortsByName <- function(pattern, negate = FALSE, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  definitionsMetaData <- getCohortDefinitionsMetaData(baseUrl = baseUrl)
  matched <- definitionsMetaData %>% dplyr::filter(stringr::str_detect(string = .data$name,
                                                                       pattern = pattern,
                                                                       negate = negate))
  if (nrow(matched) > 0) {
    return(matched)
  } else {
    return(FALSE)
  }
}




#' Post Cohort definition. 
#' @details
#' Post Cohort definition to WebAPI
#'
#' @template BaseUrl
#' @param name               A valid name for the definition. WebApi will use this name (if valid) as
#'                           the name of the definition. WebApi checks for validity, such as
#'                           uniqueness, absence of unacceptable character etc. An error might be
#'                           thrown.
#' @param cohortDefinition   An R list object containing the expression for the specification. This
#'                           will be converted to JSON expression by function and posted into the
#'                           WebApi. Note: only limited checks are performed in R to check the validity
#'                           of this expression.
#' @return
#' This function will return a dataframe object with one row describing the posted WebApi expression
#' and its details. If unsuccessful a STOP message will be shown.
#'
#' @examples
#' \dontrun{
#' postCohortDefinition(name = "new valid name",
#'                      cohortDefinition = definition,
#'                      baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
postCohortDefinition <- function(name, cohortDefinition, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- postDefinition(name = name,
                           baseUrl = baseUrl,
                           category = "cohort",
                           definition = cohortDefinition)
  return(result)
}


#' Update a Cohort definition. 
#' @details
#' Update a Cohort definition.
#'
#' @template BaseUrl
#' @param cohortDefinition   An R list object containing the expression for the specification. Must
#'                           include id, name and expression. This will be converted to JSON expression
#'                           by function and posted into the WebApi. The definition will be checked
#'                           against the WebApi instance for errors
#'
#' @examples
#' \dontrun{
#' definition <- getCohortDefinition(id = 13242,
#'                                   baseUrl = "http://server.org:80/WebAPI",
#'                                   category = cohort)
#' definition$name <- "My new name for this"
#' updateCohort(cohortDefinition, baseUrl, category = "cohort")
#' }
#' @export
# Check name
updateCohortDefinition <- function(cohortDefinition, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- updateDefinition(baseUrl = baseUrl,
                             definition = cohortDefinition,
                             category = "cohort")
  return(result)
}


#' Get generation information for Cohort id.
#'
#' @details
#' Get generation (execution) information about Cohort for a cohortId.
#'
#' @template BaseUrl
#' @param cohortId   An integer id representing the id that uniquely identifies a Cohort definition in
#'                   a WebApi instance.
#' @return
#' An R object representing the Cohort definition
#'
#' @examples
#' \dontrun{
#' getCohortGenerationInformation(cohortId = 13242, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getCohortGenerationInformation <- function(cohortId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  .checkBaseUrl(baseUrl)
  response <- getGenerationInformation(id = cohortId, baseUrl = baseUrl, category = "cohort")
  return(response)
}


#' Invoke generation of Cohort id.
#'
#' @details
#' Invoke the generation of Cohort id in the WebApi.
#'
#' @template BaseUrl
#' @param cohortId   An integer id representing the id that uniquely identifies a Cohort definition in
#'                   a WebApi instance.
#' @template SourceKey
#' @return
#' A tibble with job status information.
#'
#' @examples
#' \dontrun{
#' invokeCohortGeneration(cohortId = 13242,
#'                        baseUrl = "http://server.org:80/WebAPI",
#'                        sourceKey = "HCUP")
#' }
#' @export
invokeCohortGeneration <- function(cohortId, baseUrl, sourceKey) {
  baseUrl <- gsub("/$", "", baseUrl)
  .checkBaseUrl(baseUrl)
  response <- invokeGeneration(id = cohortId,
                               baseUrl = baseUrl,
                               category = "cohort",
                               sourceKey = sourceKey)
  return(response)
}

#' Cancel generation of Cohort id.
#'
#' @details
#' Cancel the generation of Cohort id in the WebApi.
#'
#' @template BaseUrl
#' @param cohortId   An integer id representing the id that uniquely identifies a Cohort definition in
#'                   a WebApi instance.
#' @template SourceKey
#' @return
#' A tibble with job status information.
#'
#' @examples
#' \dontrun{
#' cancelCohortGeneration(cohortId = 13242,
#'                        baseUrl = "http://server.org:80/WebAPI",
#'                        sourceKey = "HCUP")
#' }
#' @export
cancelCohortGeneration <- function(cohortId, baseUrl, sourceKey) {
  .checkBaseUrl(baseUrl)
  response <- cancelGeneration(id = cohortId,
                               baseUrl = baseUrl,
                               category = "cohort",
                               sourceKey = sourceKey)
  return(response)
}


#' Get results for a Cohort Id.
#'
#' @details
#' Get the results for Cohort id.
#'
#' @template BaseUrl
#' @template CohortId
#' @return
#' An R object with results.
#'
#' @examples
#' \dontrun{
#' getCohortResults(cohortId = 342, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
getCohortResults <- function(cohortId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- getResults(baseUrl = baseUrl, id = cohortId, category = "cohort")
  return(result)
}
#' Get the meta data for IncidenceRate definitions. 
#' @details
#' Get the meta data of WebApi specifications such as id, name, created/modified details, hash object,
#' etc. from WebApi for IncidenceRate. This function is useful to retrieve the current IncidenceRate
#' specifications.
#'
#' @template BaseUrl
#' @return
#' A tibble of specification metadata for IncidenceRate. Note: modifiedDate and createdDate are
#' returned as text/character.
#'
#' @examples
#' \dontrun{
#' getIncidenceRateDefinitionsMetaData(baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getIncidenceRateDefinitionsMetaData <- function(baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  metaData <- getDefinitionsMetadata(baseUrl = baseUrl, category = c("incidenceRate"))
  return(metaData)
}


#' is IncidenceRate id a valid definition in the WebApi. 
#' @details
#' Checks if a set of id for a IncidenceRate is valid. The following checks are performed. 1) checks
#' if all the ids exists in the WebApi i.e. valid.
#'
#' @template BaseUrl
#' @param incidenceRateIds   A list of integer id(s) of the IncidenceRate to be tested for validity.
#' @return
#' A logical vector indicating if an ID is valid.
#'
#' @examples
#' \dontrun{
#' isValidIncidenceRateId(incidenceRateIds = c(13242, 3423, 34),
#'                        baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
isValidIncidenceRateId <- function(incidenceRateIds, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- isValidId(baseUrl = baseUrl, category = "incidenceRate", ids = incidenceRateIds)
  return(result)
}


#' Get IncidenceRate id definition. 
#' @details
#' Obtain the IncidenceRate definition from WebAPI for a given IncidenceRate id
#'
#' @template BaseUrl
#' @param incidenceRateId   An integer id representing the id that uniquely identifies a IncidenceRate
#'                          definition in a WebApi instance.
#' @return
#' An R object representing the IncidenceRate definition
#'
#' @examples
#' \dontrun{
#' getIncidenceRateDefinition(incidenceRateId = 13242, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getIncidenceRateDefinition <- function(incidenceRateId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- getDefinition(id = incidenceRateId, baseUrl = baseUrl, category = "incidenceRate")
  return(result)
}


#' Delete IncidenceRate id definition. 
#' @details
#' Delete the IncidenceRate definition from WebAPI for a given IncidenceRate id
#'
#' @template BaseUrl
#' @param incidenceRateId   An integer id representing the id that uniquely identifies a IncidenceRate
#'                          definition in a WebApi instance.
#' @return
#' None, unless error.
#'
#' @examples
#' \dontrun{
#' deleteIncidenceRateDefinition(incidenceRateId = 13242, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
deleteIncidenceRateDefinition <- function(incidenceRateId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- deleteDefinition(baseUrl = baseUrl, id = incidenceRateId, category = "incidenceRate")
  return(result)
}


#' Check if IncidenceRate definition name exists. 
#' @details
#' Check if a string name already exists in the WebApi as a IncidenceRate definition name.
#'
#' @template BaseUrl
#' @param incidenceRateName   A string name for the IncidenceRate to be checked.
#' @return
#' If found, the function will return a tibble with details of the specification. If not found, FALSE
#' will be returned.
#'
#' @examples
#' \dontrun{
#' existsIncidenceRateName(incidenceRateName = "this text string needs to be checked",
#'                         baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
existsIncidenceRateName <- function(incidenceRateName, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  definitionsMetaData <- getIncidenceRateDefinitionsMetaData(baseUrl = baseUrl)
  matched <- definitionsMetaData %>% dplyr::filter(.data$name == incidenceRateName)
  if (nrow(matched) > 0) {
    return(matched)
  } else {
    FALSE
  }
}


#' Detect the presence of string matched IncidenceRate definitions. 
#' @details
#' Detect string matched IncidenceRate definition names from the WebApi, and retrieve metadata
#' definitions.
#'
#' @template BaseUrl
#' @param pattern   A pattern to look for. See \link[stringr]{str_detect} for details.
#' @param negate    If TRUE, return non-matching elements. See \link[stringr]{str_detect} for details.
#' @return
#' FALSE if no matches. If matched - output from
#' \link[ROhdsiWebApi]{getIncidenceRateDefinitionsMetaData}
#'
#' @examples
#' \dontrun{
#' detectIncidenceRates(pattern = "this text string to search in pattern",
#'                      baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
detectIncidenceRatesByName <- function(pattern, negate = FALSE, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  definitionsMetaData <- getIncidenceRateDefinitionsMetaData(baseUrl = baseUrl)
  matched <- definitionsMetaData %>% dplyr::filter(stringr::str_detect(string = .data$name,
                                                                       pattern = pattern,
                                                                       negate = negate))
  if (nrow(matched) > 0) {
    return(matched)
  } else {
    return(FALSE)
  }
}




#' Post IncidenceRate definition. 
#' @details
#' Post IncidenceRate definition to WebAPI
#'
#' @template BaseUrl
#' @param name                      A valid name for the definition. WebApi will use this name (if
#'                                  valid) as the name of the definition. WebApi checks for validity,
#'                                  such as uniqueness, absence of unacceptable character etc. An error
#'                                  might be thrown.
#' @param incidenceRateDefinition   An R list object containing the expression for the specification.
#'                                  This will be converted to JSON expression by function and posted
#'                                  into the WebApi. Note: only limited checks are performed in R to
#'                                  check the validity of this expression.
#' @return
#' This function will return a dataframe object with one row describing the posted WebApi expression
#' and its details. If unsuccessful a STOP message will be shown.
#'
#' @examples
#' \dontrun{
#' postIncidenceRateDefinition(name = "new valid name",
#'                             incidenceRateDefinition = definition,
#'                             baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
postIncidenceRateDefinition <- function(name, incidenceRateDefinition, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- postDefinition(name = name,
                           baseUrl = baseUrl,
                           category = "incidenceRate",
                           definition = incidenceRateDefinition)
  return(result)
}

#' Get generation information for IncidenceRate id.
#'
#' @details
#' Get generation (execution) information about IncidenceRate for a incidenceRateId.
#'
#' @template BaseUrl
#' @param incidenceRateId   An integer id representing the id that uniquely identifies a IncidenceRate
#'                          definition in a WebApi instance.
#' @return
#' An R object representing the IncidenceRate definition
#'
#' @examples
#' \dontrun{
#' getIncidenceRateGenerationInformation(incidenceRateId = 13242,
#'                                       baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getIncidenceRateGenerationInformation <- function(incidenceRateId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  .checkBaseUrl(baseUrl)
  response <- getGenerationInformation(id = incidenceRateId,
                                       baseUrl = baseUrl,
                                       category = "incidenceRate")
  return(response)
}


#' Invoke generation of IncidenceRate id.
#'
#' @details
#' Invoke the generation of IncidenceRate id in the WebApi.
#'
#' @template BaseUrl
#' @param incidenceRateId   An integer id representing the id that uniquely identifies a IncidenceRate
#'                          definition in a WebApi instance.
#' @template SourceKey
#' @return
#' A tibble with job status information.
#'
#' @examples
#' \dontrun{
#' invokeIncidenceRateGeneration(incidenceRateId = 13242,
#'                               baseUrl = "http://server.org:80/WebAPI",
#'                               sourceKey = "HCUP")
#' }
#' @export
invokeIncidenceRateGeneration <- function(incidenceRateId, baseUrl, sourceKey) {
  baseUrl <- gsub("/$", "", baseUrl)
  .checkBaseUrl(baseUrl)
  response <- invokeGeneration(id = incidenceRateId,
                               baseUrl = baseUrl,
                               category = "incidenceRate",
                               sourceKey = sourceKey)
  return(response)
}

#' Cancel generation of IncidenceRate id.
#'
#' @details
#' Cancel the generation of IncidenceRate id in the WebApi.
#'
#' @template BaseUrl
#' @param incidenceRateId   An integer id representing the id that uniquely identifies a IncidenceRate
#'                          definition in a WebApi instance.
#' @template SourceKey
#' @return
#' A tibble with job status information.
#'
#' @examples
#' \dontrun{
#' cancelIncidenceRateGeneration(incidenceRateId = 13242,
#'                               baseUrl = "http://server.org:80/WebAPI",
#'                               sourceKey = "HCUP")
#' }
#' @export
cancelIncidenceRateGeneration <- function(incidenceRateId, baseUrl, sourceKey) {
  .checkBaseUrl(baseUrl)
  response <- cancelGeneration(id = incidenceRateId,
                               baseUrl = baseUrl,
                               category = "incidenceRate",
                               sourceKey = sourceKey)
  return(response)
}


#' Get results for a IncidenceRate Id.
#'
#' @details
#' Get the results for IncidenceRate id.
#'
#' @template BaseUrl
#' @template IncidenceRateId
#' @return
#' An R object with results.
#'
#' @examples
#' \dontrun{
#' getIncidenceRateResults(incidenceRateId = 342, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
getIncidenceRateResults <- function(incidenceRateId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- getResults(baseUrl = baseUrl, id = incidenceRateId, category = "incidenceRate")
  return(result)
}
#' Get the meta data for Estimation definitions. 
#' @details
#' Get the meta data of WebApi specifications such as id, name, created/modified details, hash object,
#' etc. from WebApi for Estimation. This function is useful to retrieve the current Estimation
#' specifications.
#'
#' @template BaseUrl
#' @return
#' A tibble of specification metadata for Estimation. Note: modifiedDate and createdDate are returned
#' as text/character.
#'
#' @examples
#' \dontrun{
#' getEstimationDefinitionsMetaData(baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getEstimationDefinitionsMetaData <- function(baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  metaData <- getDefinitionsMetadata(baseUrl = baseUrl, category = c("estimation"))
  return(metaData)
}


#' is Estimation id a valid definition in the WebApi. 
#' @details
#' Checks if a set of id for a Estimation is valid. The following checks are performed. 1) checks if
#' all the ids exists in the WebApi i.e. valid.
#'
#' @template BaseUrl
#' @param estimationIds   A list of integer id(s) of the Estimation to be tested for validity.
#' @return
#' A logical vector indicating if an ID is valid.
#'
#' @examples
#' \dontrun{
#' isValidEstimationId(estimationIds = c(13242, 3423, 34), baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
isValidEstimationId <- function(estimationIds, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- isValidId(baseUrl = baseUrl, category = "estimation", ids = estimationIds)
  return(result)
}


#' Get Estimation id definition. 
#' @details
#' Obtain the Estimation definition from WebAPI for a given Estimation id
#'
#' @template BaseUrl
#' @param estimationId   An integer id representing the id that uniquely identifies a Estimation
#'                       definition in a WebApi instance.
#' @return
#' An R object representing the Estimation definition
#'
#' @examples
#' \dontrun{
#' getEstimationDefinition(estimationId = 13242, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getEstimationDefinition <- function(estimationId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- getDefinition(id = estimationId, baseUrl = baseUrl, category = "estimation")
  return(result)
}


#' Delete Estimation id definition. 
#' @details
#' Delete the Estimation definition from WebAPI for a given Estimation id
#'
#' @template BaseUrl
#' @param estimationId   An integer id representing the id that uniquely identifies a Estimation
#'                       definition in a WebApi instance.
#' @return
#' None, unless error.
#'
#' @examples
#' \dontrun{
#' deleteEstimationDefinition(estimationId = 13242, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
deleteEstimationDefinition <- function(estimationId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- deleteDefinition(baseUrl = baseUrl, id = estimationId, category = "estimation")
  return(result)
}


#' Check if Estimation definition name exists. 
#' @details
#' Check if a string name already exists in the WebApi as a Estimation definition name.
#'
#' @template BaseUrl
#' @param estimationName   A string name for the Estimation to be checked.
#' @return
#' If found, the function will return a tibble with details of the specification. If not found, FALSE
#' will be returned.
#'
#' @examples
#' \dontrun{
#' existsEstimationName(estimationName = "this text string needs to be checked",
#'                      baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
existsEstimationName <- function(estimationName, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  definitionsMetaData <- getEstimationDefinitionsMetaData(baseUrl = baseUrl)
  matched <- definitionsMetaData %>% dplyr::filter(.data$name == estimationName)
  if (nrow(matched) > 0) {
    return(matched)
  } else {
    FALSE
  }
}


#' Detect the presence of string matched Estimation definitions. 
#' @details
#' Detect string matched Estimation definition names from the WebApi, and retrieve metadata
#' definitions.
#'
#' @template BaseUrl
#' @param pattern   A pattern to look for. See \link[stringr]{str_detect} for details.
#' @param negate    If TRUE, return non-matching elements. See \link[stringr]{str_detect} for details.
#' @return
#' FALSE if no matches. If matched - output from \link[ROhdsiWebApi]{getEstimationDefinitionsMetaData}
#'
#' @examples
#' \dontrun{
#' detectEstimations(pattern = "this text string to search in pattern",
#'                   baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
detectEstimationsByName <- function(pattern, negate = FALSE, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  definitionsMetaData <- getEstimationDefinitionsMetaData(baseUrl = baseUrl)
  matched <- definitionsMetaData %>% dplyr::filter(stringr::str_detect(string = .data$name,
                                                                       pattern = pattern,
                                                                       negate = negate))
  if (nrow(matched) > 0) {
    return(matched)
  } else {
    return(FALSE)
  }
}




#' Post Estimation definition. 
#' @details
#' Post Estimation definition to WebAPI
#'
#' @template BaseUrl
#' @param name                   A valid name for the definition. WebApi will use this name (if valid)
#'                               as the name of the definition. WebApi checks for validity, such as
#'                               uniqueness, absence of unacceptable character etc. An error might be
#'                               thrown.
#' @param estimationDefinition   An R list object containing the expression for the specification. This
#'                               will be converted to JSON expression by function and posted into the
#'                               WebApi. Note: only limited checks are performed in R to check the
#'                               validity of this expression.
#' @return
#' This function will return a dataframe object with one row describing the posted WebApi expression
#' and its details. If unsuccessful a STOP message will be shown.
#'
#' @examples
#' \dontrun{
#' postEstimationDefinition(name = "new valid name",
#'                          estimationDefinition = definition,
#'                          baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
postEstimationDefinition <- function(name, estimationDefinition, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- postDefinition(name = name,
                           baseUrl = baseUrl,
                           category = "estimation",
                           definition = estimationDefinition)
  return(result)
}


#' Get the meta data for Prediction definitions. 
#' @details
#' Get the meta data of WebApi specifications such as id, name, created/modified details, hash object,
#' etc. from WebApi for Prediction. This function is useful to retrieve the current Prediction
#' specifications.
#'
#' @template BaseUrl
#' @return
#' A tibble of specification metadata for Prediction. Note: modifiedDate and createdDate are returned
#' as text/character.
#'
#' @examples
#' \dontrun{
#' getPredictionDefinitionsMetaData(baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getPredictionDefinitionsMetaData <- function(baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  metaData <- getDefinitionsMetadata(baseUrl = baseUrl, category = c("prediction"))
  return(metaData)
}


#' is Prediction id a valid definition in the WebApi. 
#' @details
#' Checks if a set of id for a Prediction is valid. The following checks are performed. 1) checks if
#' all the ids exists in the WebApi i.e. valid.
#'
#' @template BaseUrl
#' @param predictionIds   A list of integer id(s) of the Prediction to be tested for validity.
#' @return
#' A logical vector indicating if an ID is valid.
#'
#' @examples
#' \dontrun{
#' isValidPredictionId(predictionIds = c(13242, 3423, 34), baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
isValidPredictionId <- function(predictionIds, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- isValidId(baseUrl = baseUrl, category = "prediction", ids = predictionIds)
  return(result)
}


#' Get Prediction id definition. 
#' @details
#' Obtain the Prediction definition from WebAPI for a given Prediction id
#'
#' @template BaseUrl
#' @param predictionId   An integer id representing the id that uniquely identifies a Prediction
#'                       definition in a WebApi instance.
#' @return
#' An R object representing the Prediction definition
#'
#' @examples
#' \dontrun{
#' getPredictionDefinition(predictionId = 13242, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getPredictionDefinition <- function(predictionId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- getDefinition(id = predictionId, baseUrl = baseUrl, category = "prediction")
  return(result)
}


#' Delete Prediction id definition. 
#' @details
#' Delete the Prediction definition from WebAPI for a given Prediction id
#'
#' @template BaseUrl
#' @param predictionId   An integer id representing the id that uniquely identifies a Prediction
#'                       definition in a WebApi instance.
#' @return
#' None, unless error.
#'
#' @examples
#' \dontrun{
#' deletePredictionDefinition(predictionId = 13242, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
deletePredictionDefinition <- function(predictionId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- deleteDefinition(baseUrl = baseUrl, id = predictionId, category = "prediction")
  return(result)
}


#' Check if Prediction definition name exists. 
#' @details
#' Check if a string name already exists in the WebApi as a Prediction definition name.
#'
#' @template BaseUrl
#' @param predictionName   A string name for the Prediction to be checked.
#' @return
#' If found, the function will return a tibble with details of the specification. If not found, FALSE
#' will be returned.
#'
#' @examples
#' \dontrun{
#' existsPredictionName(predictionName = "this text string needs to be checked",
#'                      baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
existsPredictionName <- function(predictionName, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  definitionsMetaData <- getPredictionDefinitionsMetaData(baseUrl = baseUrl)
  matched <- definitionsMetaData %>% dplyr::filter(.data$name == predictionName)
  if (nrow(matched) > 0) {
    return(matched)
  } else {
    FALSE
  }
}


#' Detect the presence of string matched Prediction definitions. 
#' @details
#' Detect string matched Prediction definition names from the WebApi, and retrieve metadata
#' definitions.
#'
#' @template BaseUrl
#' @param pattern   A pattern to look for. See \link[stringr]{str_detect} for details.
#' @param negate    If TRUE, return non-matching elements. See \link[stringr]{str_detect} for details.
#' @return
#' FALSE if no matches. If matched - output from \link[ROhdsiWebApi]{getPredictionDefinitionsMetaData}
#'
#' @examples
#' \dontrun{
#' detectPredictions(pattern = "this text string to search in pattern",
#'                   baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
detectPredictionsByName <- function(pattern, negate = FALSE, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  definitionsMetaData <- getPredictionDefinitionsMetaData(baseUrl = baseUrl)
  matched <- definitionsMetaData %>% dplyr::filter(stringr::str_detect(string = .data$name,
                                                                       pattern = pattern,
                                                                       negate = negate))
  if (nrow(matched) > 0) {
    return(matched)
  } else {
    return(FALSE)
  }
}




#' Post Prediction definition. 
#' @details
#' Post Prediction definition to WebAPI
#'
#' @template BaseUrl
#' @param name                   A valid name for the definition. WebApi will use this name (if valid)
#'                               as the name of the definition. WebApi checks for validity, such as
#'                               uniqueness, absence of unacceptable character etc. An error might be
#'                               thrown.
#' @param predictionDefinition   An R list object containing the expression for the specification. This
#'                               will be converted to JSON expression by function and posted into the
#'                               WebApi. Note: only limited checks are performed in R to check the
#'                               validity of this expression.
#' @return
#' This function will return a dataframe object with one row describing the posted WebApi expression
#' and its details. If unsuccessful a STOP message will be shown.
#'
#' @examples
#' \dontrun{
#' postPredictionDefinition(name = "new valid name",
#'                          predictionDefinition = definition,
#'                          baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
postPredictionDefinition <- function(name, predictionDefinition, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- postDefinition(name = name,
                           baseUrl = baseUrl,
                           category = "prediction",
                           definition = predictionDefinition)
  return(result)
}

#' Get the meta data for Characterization definitions. 
#' @details
#' Get the meta data of WebApi specifications such as id, name, created/modified details, hash object,
#' etc. from WebApi for Characterization. This function is useful to retrieve the current
#' Characterization specifications.
#'
#' @template BaseUrl
#' @return
#' A tibble of specification metadata for Characterization. Note: modifiedDate and createdDate are
#' returned as text/character.
#'
#' @examples
#' \dontrun{
#' getCharacterizationDefinitionsMetaData(baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getCharacterizationDefinitionsMetaData <- function(baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  metaData <- getDefinitionsMetadata(baseUrl = baseUrl, category = c("characterization"))
  return(metaData)
}


#' is Characterization id a valid definition in the WebApi. 
#' @details
#' Checks if a set of id for a Characterization is valid. The following checks are performed. 1)
#' checks if all the ids exists in the WebApi i.e. valid.
#'
#' @template BaseUrl
#' @param characterizationIds   A list of integer id(s) of the Characterization to be tested for
#'                              validity.
#' @return
#' A logical vector indicating if an ID is valid.
#'
#' @examples
#' \dontrun{
#' isValidCharacterizationId(characterizationIds = c(13242, 3423, 34),
#'                           baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
isValidCharacterizationId <- function(characterizationIds, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- isValidId(baseUrl = baseUrl, category = "characterization", ids = characterizationIds)
  return(result)
}


#' Get Characterization id definition. 
#' @details
#' Obtain the Characterization definition from WebAPI for a given Characterization id
#'
#' @template BaseUrl
#' @param characterizationId   An integer id representing the id that uniquely identifies a
#'                             Characterization definition in a WebApi instance.
#' @return
#' An R object representing the Characterization definition
#'
#' @examples
#' \dontrun{
#' getCharacterizationDefinition(characterizationId = 13242,
#'                               baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getCharacterizationDefinition <- function(characterizationId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- getDefinition(id = characterizationId, baseUrl = baseUrl, category = "characterization")
  return(result)
}


#' Delete Characterization id definition. 
#' @details
#' Delete the Characterization definition from WebAPI for a given Characterization id
#'
#' @template BaseUrl
#' @param characterizationId   An integer id representing the id that uniquely identifies a
#'                             Characterization definition in a WebApi instance.
#' @return
#' None, unless error.
#'
#' @examples
#' \dontrun{
#' deleteCharacterizationDefinition(characterizationId = 13242,
#'                                  baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
deleteCharacterizationDefinition <- function(characterizationId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- deleteDefinition(baseUrl = baseUrl,
                             id = characterizationId,
                             category = "characterization")
  return(result)
}


#' Check if Characterization definition name exists. 
#' @details
#' Check if a string name already exists in the WebApi as a Characterization definition name.
#'
#' @template BaseUrl
#' @param characterizationName   A string name for the Characterization to be checked.
#' @return
#' If found, the function will return a tibble with details of the specification. If not found, FALSE
#' will be returned.
#'
#' @examples
#' \dontrun{
#' existsCharacterizationName(characterizationName = "this text string needs to be checked",
#'                            baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
existsCharacterizationName <- function(characterizationName, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  definitionsMetaData <- getCharacterizationDefinitionsMetaData(baseUrl = baseUrl)
  matched <- definitionsMetaData %>% dplyr::filter(.data$name == characterizationName)
  if (nrow(matched) > 0) {
    return(matched)
  } else {
    FALSE
  }
}


#' Detect the presence of string matched Characterization definitions. 
#' @details
#' Detect string matched Characterization definition names from the WebApi, and retrieve metadata
#' definitions.
#'
#' @template BaseUrl
#' @param pattern   A pattern to look for. See \link[stringr]{str_detect} for details.
#' @param negate    If TRUE, return non-matching elements. See \link[stringr]{str_detect} for details.
#' @return
#' FALSE if no matches. If matched - output from
#' \link[ROhdsiWebApi]{getCharacterizationDefinitionsMetaData}
#'
#' @examples
#' \dontrun{
#' detectCharacterizations(pattern = "this text string to search in pattern",
#'                         baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
detectCharacterizationsByName <- function(pattern, negate = FALSE, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  definitionsMetaData <- getCharacterizationDefinitionsMetaData(baseUrl = baseUrl)
  matched <- definitionsMetaData %>% dplyr::filter(stringr::str_detect(string = .data$name,
                                                                       pattern = pattern,
                                                                       negate = negate))
  if (nrow(matched) > 0) {
    return(matched)
  } else {
    return(FALSE)
  }
}




#' Post Characterization definition. 
#' @details
#' Post Characterization definition to WebAPI
#'
#' @template BaseUrl
#' @param name                         A valid name for the definition. WebApi will use this name (if
#'                                     valid) as the name of the definition. WebApi checks for
#'                                     validity, such as uniqueness, absence of unacceptable character
#'                                     etc. An error might be thrown.
#' @param characterizationDefinition   An R list object containing the expression for the
#'                                     specification. This will be converted to JSON expression by
#'                                     function and posted into the WebApi. Note: only limited checks
#'                                     are performed in R to check the validity of this expression.
#' @return
#' This function will return a dataframe object with one row describing the posted WebApi expression
#' and its details. If unsuccessful a STOP message will be shown.
#'
#' @examples
#' \dontrun{
#' postCharacterizationDefinition(name = "new valid name",
#'                                characterizationDefinition = definition,
#'                                baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
postCharacterizationDefinition <- function(name, characterizationDefinition, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- postDefinition(name = name,
                           baseUrl = baseUrl,
                           category = "characterization",
                           definition = characterizationDefinition)
  return(result)
}

#' Get generation information for Characterization id.
#'
#' @details
#' Get generation (execution) information about Characterization for a characterizationId.
#'
#' @template BaseUrl
#' @param characterizationId   An integer id representing the id that uniquely identifies a
#'                             Characterization definition in a WebApi instance.
#' @return
#' An R object representing the Characterization definition
#'
#' @examples
#' \dontrun{
#' getCharacterizationGenerationInformation(characterizationId = 13242,
#'                                          baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getCharacterizationGenerationInformation <- function(characterizationId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  .checkBaseUrl(baseUrl)
  response <- getGenerationInformation(id = characterizationId,
                                       baseUrl = baseUrl,
                                       category = "characterization")
  return(response)
}


#' Invoke generation of Characterization id.
#'
#' @details
#' Invoke the generation of Characterization id in the WebApi.
#'
#' @template BaseUrl
#' @param characterizationId   An integer id representing the id that uniquely identifies a
#'                             Characterization definition in a WebApi instance.
#' @template SourceKey
#' @return
#' A tibble with job status information.
#'
#' @examples
#' \dontrun{
#' invokeCharacterizationGeneration(characterizationId = 13242,
#'                                  baseUrl = "http://server.org:80/WebAPI",
#'                                  sourceKey = "HCUP")
#' }
#' @export
invokeCharacterizationGeneration <- function(characterizationId, baseUrl, sourceKey) {
  baseUrl <- gsub("/$", "", baseUrl)
  .checkBaseUrl(baseUrl)
  response <- invokeGeneration(id = characterizationId,
                               baseUrl = baseUrl,
                               category = "characterization",
                               sourceKey = sourceKey)
  return(response)
}

#' Cancel generation of Characterization id.
#'
#' @details
#' Cancel the generation of Characterization id in the WebApi.
#'
#' @template BaseUrl
#' @param characterizationId   An integer id representing the id that uniquely identifies a
#'                             Characterization definition in a WebApi instance.
#' @template SourceKey
#' @return
#' A tibble with job status information.
#'
#' @examples
#' \dontrun{
#' cancelCharacterizationGeneration(characterizationId = 13242,
#'                                  baseUrl = "http://server.org:80/WebAPI",
#'                                  sourceKey = "HCUP")
#' }
#' @export
cancelCharacterizationGeneration <- function(characterizationId, baseUrl, sourceKey) {
  .checkBaseUrl(baseUrl)
  response <- cancelGeneration(id = characterizationId,
                               baseUrl = baseUrl,
                               category = "characterization",
                               sourceKey = sourceKey)
  return(response)
}


#' Get results for a Characterization Id.
#'
#' @details
#' Get the results for Characterization id.
#'
#' @template BaseUrl
#' @template CharacterizationId
#' @return
#' An R object with results.
#'
#' @examples
#' \dontrun{
#' getCharacterizationResults(characterizationId = 342, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
getCharacterizationResults <- function(characterizationId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- getResults(baseUrl = baseUrl, id = characterizationId, category = "characterization")
  return(result)
}
#' Get the meta data for Pathway definitions. 
#' @details
#' Get the meta data of WebApi specifications such as id, name, created/modified details, hash object,
#' etc. from WebApi for Pathway. This function is useful to retrieve the current Pathway
#' specifications.
#'
#' @template BaseUrl
#' @return
#' A tibble of specification metadata for Pathway. Note: modifiedDate and createdDate are returned as
#' text/character.
#'
#' @examples
#' \dontrun{
#' getPathwayDefinitionsMetaData(baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getPathwayDefinitionsMetaData <- function(baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  metaData <- getDefinitionsMetadata(baseUrl = baseUrl, category = c("pathway"))
  return(metaData)
}


#' is Pathway id a valid definition in the WebApi. 
#' @details
#' Checks if a set of id for a Pathway is valid. The following checks are performed. 1) checks if all
#' the ids exists in the WebApi i.e. valid.
#'
#' @template BaseUrl
#' @param pathwayIds   A list of integer id(s) of the Pathway to be tested for validity.
#' @return
#' A logical vector indicating if an ID is valid.
#'
#' @examples
#' \dontrun{
#' isValidPathwayId(pathwayIds = c(13242, 3423, 34), baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
isValidPathwayId <- function(pathwayIds, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- isValidId(baseUrl = baseUrl, category = "pathway", ids = pathwayIds)
  return(result)
}


#' Get Pathway id definition. 
#' @details
#' Obtain the Pathway definition from WebAPI for a given Pathway id
#'
#' @template BaseUrl
#' @param pathwayId   An integer id representing the id that uniquely identifies a Pathway definition
#'                    in a WebApi instance.
#' @return
#' An R object representing the Pathway definition
#'
#' @examples
#' \dontrun{
#' getPathwayDefinition(pathwayId = 13242, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getPathwayDefinition <- function(pathwayId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- getDefinition(id = pathwayId, baseUrl = baseUrl, category = "pathway")
  return(result)
}


#' Delete Pathway id definition. 
#' @details
#' Delete the Pathway definition from WebAPI for a given Pathway id
#'
#' @template BaseUrl
#' @param pathwayId   An integer id representing the id that uniquely identifies a Pathway definition
#'                    in a WebApi instance.
#' @return
#' None, unless error.
#'
#' @examples
#' \dontrun{
#' deletePathwayDefinition(pathwayId = 13242, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
deletePathwayDefinition <- function(pathwayId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- deleteDefinition(baseUrl = baseUrl, id = pathwayId, category = "pathway")
  return(result)
}


#' Check if Pathway definition name exists. 
#' @details
#' Check if a string name already exists in the WebApi as a Pathway definition name.
#'
#' @template BaseUrl
#' @param pathwayName   A string name for the Pathway to be checked.
#' @return
#' If found, the function will return a tibble with details of the specification. If not found, FALSE
#' will be returned.
#'
#' @examples
#' \dontrun{
#' existsPathwayName(pathwayName = "this text string needs to be checked",
#'                   baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
existsPathwayName <- function(pathwayName, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  definitionsMetaData <- getPathwayDefinitionsMetaData(baseUrl = baseUrl)
  matched <- definitionsMetaData %>% dplyr::filter(.data$name == pathwayName)
  if (nrow(matched) > 0) {
    return(matched)
  } else {
    FALSE
  }
}


#' Detect the presence of string matched Pathway definitions. 
#' @details
#' Detect string matched Pathway definition names from the WebApi, and retrieve metadata definitions.
#'
#' @template BaseUrl
#' @param pattern   A pattern to look for. See \link[stringr]{str_detect} for details.
#' @param negate    If TRUE, return non-matching elements. See \link[stringr]{str_detect} for details.
#' @return
#' FALSE if no matches. If matched - output from \link[ROhdsiWebApi]{getPathwayDefinitionsMetaData}
#'
#' @examples
#' \dontrun{
#' detectPathways(pattern = "this text string to search in pattern",
#'                baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
detectPathwaysByName <- function(pattern, negate = FALSE, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  definitionsMetaData <- getPathwayDefinitionsMetaData(baseUrl = baseUrl)
  matched <- definitionsMetaData %>% dplyr::filter(stringr::str_detect(string = .data$name,
                                                                       pattern = pattern,
                                                                       negate = negate))
  if (nrow(matched) > 0) {
    return(matched)
  } else {
    return(FALSE)
  }
}




#' Post Pathway definition. 
#' @details
#' Post Pathway definition to WebAPI
#'
#' @template BaseUrl
#' @param name                A valid name for the definition. WebApi will use this name (if valid) as
#'                            the name of the definition. WebApi checks for validity, such as
#'                            uniqueness, absence of unacceptable character etc. An error might be
#'                            thrown.
#' @param pathwayDefinition   An R list object containing the expression for the specification. This
#'                            will be converted to JSON expression by function and posted into the
#'                            WebApi. Note: only limited checks are performed in R to check the
#'                            validity of this expression.
#' @return
#' This function will return a dataframe object with one row describing the posted WebApi expression
#' and its details. If unsuccessful a STOP message will be shown.
#'
#' @examples
#' \dontrun{
#' postPathwayDefinition(name = "new valid name",
#'                       pathwayDefinition = definition,
#'                       baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
postPathwayDefinition <- function(name, pathwayDefinition, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- postDefinition(name = name,
                           baseUrl = baseUrl,
                           category = "pathway",
                           definition = pathwayDefinition)
  return(result)
}

#' Get generation information for Pathway id.
#'
#' @details
#' Get generation (execution) information about Pathway for a pathwayId.
#'
#' @template BaseUrl
#' @param pathwayId   An integer id representing the id that uniquely identifies a Pathway definition
#'                    in a WebApi instance.
#' @return
#' An R object representing the Pathway definition
#'
#' @examples
#' \dontrun{
#' getPathwayGenerationInformation(pathwayId = 13242, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
getPathwayGenerationInformation <- function(pathwayId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  .checkBaseUrl(baseUrl)
  response <- getGenerationInformation(id = pathwayId, baseUrl = baseUrl, category = "pathway")
  return(response)
}


#' Invoke generation of Pathway id.
#'
#' @details
#' Invoke the generation of Pathway id in the WebApi.
#'
#' @template BaseUrl
#' @param pathwayId   An integer id representing the id that uniquely identifies a Pathway definition
#'                    in a WebApi instance.
#' @template SourceKey
#' @return
#' A tibble with job status information.
#'
#' @examples
#' \dontrun{
#' invokePathwayGeneration(pathwayId = 13242,
#'                         baseUrl = "http://server.org:80/WebAPI",
#'                         sourceKey = "HCUP")
#' }
#' @export
invokePathwayGeneration <- function(pathwayId, baseUrl, sourceKey) {
  baseUrl <- gsub("/$", "", baseUrl)
  .checkBaseUrl(baseUrl)
  response <- invokeGeneration(id = pathwayId,
                               baseUrl = baseUrl,
                               category = "pathway",
                               sourceKey = sourceKey)
  return(response)
}

#' Cancel generation of Pathway id.
#'
#' @details
#' Cancel the generation of Pathway id in the WebApi.
#'
#' @template BaseUrl
#' @param pathwayId   An integer id representing the id that uniquely identifies a Pathway definition
#'                    in a WebApi instance.
#' @template SourceKey
#' @return
#' A tibble with job status information.
#'
#' @examples
#' \dontrun{
#' cancelPathwayGeneration(pathwayId = 13242,
#'                         baseUrl = "http://server.org:80/WebAPI",
#'                         sourceKey = "HCUP")
#' }
#' @export
cancelPathwayGeneration <- function(pathwayId, baseUrl, sourceKey) {
  .checkBaseUrl(baseUrl)
  response <- cancelGeneration(id = pathwayId,
                               baseUrl = baseUrl,
                               category = "pathway",
                               sourceKey = sourceKey)
  return(response)
}


#' Get results for a Pathway Id.
#'
#' @details
#' Get the results for Pathway id.
#'
#' @template BaseUrl
#' @template PathwayId
#' @return
#' An R object with results.
#'
#' @examples
#' \dontrun{
#' getPathwayResults(pathwayId = 342, baseUrl = "http://server.org:80/WebAPI")
#' }
#' @export
# Check name
getPathwayResults <- function(pathwayId, baseUrl) {
  baseUrl <- gsub("/$", "", baseUrl)
  result <- getResults(baseUrl = baseUrl, id = pathwayId, category = "pathway")
  return(result)
}